NAV Navbar
cURL Python Elixir

Introduction

IdealSpot provides unique location intelligence to better align commercial real-estate location with consumer intent. We take traditional identity datasets and combine them with our proprietary and innovative intent datasets to provide unparalleled information which gives you with a better understanding of your market.

Hello World

Request/Response Format

Success Response

{
  'data': [
   ...
  ]
}

Error Response

{
  'errors': [
    ...
  ]
}

The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200 OK HTTP status.

Successful responses will return data while unsuccessful responses will return errors with corresponding http status codes.

JSONP Support

JSONP is not currently supported in this version.

Errors

Occasionally you might encounter errors when accessing the REST API. There are four possible types:

Error Code Error Type
400 Bad Request Invalid request, e.g. using an unsupported HTTP method
401 Unauthorized Authentication or permission error, e.g. incorrect API keys
404 Not Found Requests to resources that don't exist or are missing
500 Internal Server Error Server error

Parameters

Almost all endpoints accept optional parameters which can be passed as a HTTP query string parameter, e.g. GET /orders?status=completed. All parameters are documented along each endpoint.

Getting Started

To use the IdealSpot Geodata Platform, you'll need to register for a valid API key.

General Availability

IdealSpot Geodata v1 uses RapidAPI.com to manage authentication and access to our platform. Create an account on RapidAPI and subscribe to our API Service to get a RapidAPI authorization token.

Enterprise Tier

If you have something custom in mind, please contact us.

SDK

The following SDKs are available for Enterprise use:

Models

The following JSON models are used for request / responses.

Location

Examples 2 Mile Radius Ring

{
 "units":"miles",
 "type":"buffer",
 "radius":"2",
 "longitude":-97.7356077,
 "latitude":30.264757,
 "areatype":"ring"
 }

30 Minute Walktime Ring

{
"units":"minutes",
"type":"buffer",
"radius":"30",
"longitude":-97.7356077,
"latitude":30.264757,
"areatype":"walktime"
}

Region: Zipcode

{
"type":"region",
"regiontype": "zipcode",
"region_id": "78702"
}

Region: County

{
"type":"region",
"regiontype": "county",
"region_id": "TravisCountyTX"
}

Region: 2-word County

{
"type":"region",
"regiontype": "county",
"region_id": "Black HawkCountyIA"
}

Region: Census Tract ie., {'NAME': 'Census Tract 6.05, Dallas County, Texas', 'state': '48', 'county': '113', 'tract': '000605'}

{
"type":"region",
"regiontype": "tract",
"region_id": "48113000605"
}

Region: Census Block Group {'NAME': 'Block Group 2, Census Tract 6.05, Dallas County, Texas', 'state': '48', 'county': '113', 'tract': '000605', 'block group': '2'},

{
    "type":"region",
    "regiontype": "blockgroup",
    "region_id": 481130006052
}

Buffer

Parameters

Name Description Required Type
type Location type, ie, buffer Yes string
areatype Enum {ring, drivetime, biketime, transittime} Yes string
latitude latitude of the center point Yes number
longitude longitude of the center point Yes number
radius Radius in units specified of buffer Yes number
units Radius units Yes number

When type is buffer, include the above parameters for Buffer in the Location object.

Region

Name Description Required Type
type Location type, ie, region Yes string
region_id Region ID Yes string
regiontype Enum {nation, state, county, place, cbsa, city, zipcode, tract, blockgroup} Yes string

When type is region, include the above parameters for Region in the Location object. ie., if regiontype=zipcode, region_id={ZipCode, ie., 78702}

Region Types

Region Type Description
nation Nation code. Only US is supported
state US State code. ie, TX
county US County code in the generalized pattern of <county name>County<state abbrev>, ie. TravisCountyTX. There is a quirk where if two or more words, the format is like "Black HawkCountyIA"
city @TODO
zipcode US Zipcode, ie. 78702
cbsa Core-based statistical area. ie., Austin-RoundRockTX
place US Census Place
tract US Census Tract. Use FIPS as the region id
blockgroup Census Block Group. Use FIPS as the region_id

Custom

When type is custom, include the parameters for Custom Polygon in the Location object. This is not supported for general use.

Insights API

To query demographics, spending, and other retail market insights, use the endpoints under the "Geodata" heading. "Insights" can be thought of as a unique dataset you can query. ie., residential population counts, avg. household incomes, home values, mortgage risk, and languages spoken.

To see the full list of Insights currently available to query, visit: https://developer.idealspot.com/data

Insight Data Dictionary

GET

Get All Insights

# Get Insights
url = "https://idealgeo.com/api/v1/data/insights"
headers = {
    "accept": "application/json",
    "api_key": API_KEY
}

r = requests.get(url=url, headers=headers)
data = r.json().get('data')
for d in data:
    print('%s, %s, %s' % (d['id'], d['version'], d['description']))

Description: Returns all insights from the system that the user has access to. See above for a list of available Insights.

HTTP Request

GET /api/v1/data/insights

Parameters

Name Located in Description Required Type
api_key header Access token. Yes string

Responses

Code Description
200 A list of insights with human-readable names and short descriptions.
400 Client error (probably invalid parameters).
401 Invalid API key.
500 Internal server error.

Insight Request Definition

GET

Request

# Get `gender` meta data
url = "https://idealgeo.com/api/v1/data/insights/gender"
headers = {
    "accept": "application/json",
    "api_key": API_KEY
}

params = {
    "version": "v2",
}

r = requests.get(url=url, params=params, headers=headers)
r.json()

Response

{
  'data':
  {
    'version': 'v2',
    'url_prefix': 'trends',
    'slug': 'gender',
    'query_builder': 'synergos',
    'periods': ['YR2029Q4', 'YR2024Q4', 'YR2019Q4'],
    'parameters': {},
    'name': 'Gender',
    'groups': ['Males', 'Females', 'context.residential-population', 'context.landarea'],
    'description': 'Current year gender populations.'
  }
}

Description: Fetch request/response structure metadata for a given insight. This metadata provides parameters, time periods, and data set groupings that is querieable.

HTTP Request

GET /api/v1/data/insights/{id}

Parameters

Name Located in Description Required Type
api_key header Access token. Yes string
id path Insight ID. Yes string
version query Insight version (default latest) No string
parameters query Include parameters field (default True) No boolean
parameter_options query Include a list of valid options for each query parameter when parameters is true. No boolean
periods query Include list of time periods (fiscal years and quarters) available for this insight. (default True) No boolean
groups query Include list of groups (default True) No boolean
display_group query Include a list of display groups. Display groups are subsets of groups, usually (but not always) dividing groups by the units of the results. No string

Responses

Code Description
200 Insight metadata, filtered according to the query parameters
400 Client error (probably invalid parameters).
401 Invalid API key.
500 Internal server error.

Insight Request

GET

Get Gender for a Location

# Raw pull
url = "https://idealgeo.com/api/v1/data/insights/gender/query"

location = {
 "units":"minutes",
 "type":"buffer",
 "radius":"5",
 "longitude": -97.7356077,
 "latitude":30.264757,
 "areatype":"drivetime"
 }

headers = {
    "accept": "application/json",
    "api_key": API_KEY
}

params = {
    "version": "v2",
    "location[]": json.dumps(location),
    "startdate": "1950-01-01",
    "enddate": "2100-01-01"
}

r = requests.get(url=url, params=params, headers=headers)
r.json()

Description: Execute a search query for a given Insight. For example, if you used the "residential-population" insight for a zipcode bounded location geojson object, then historical, current, and forecasted number of people living in houses and apartments within that zipcode would be returned.

HTTP Request

GET /api/v1/data/insights/{id}/query

Parameters

Name Located in Description Required Type
api_key header Access token. Yes string
id path Insight ID (see /insights for a list of insights). Yes string
version query Insight version. Insight versions are incremented when a response format changes in any way, including the addition of new groups. Old versions are retained, unmodified, for backwards compatibility. Yes string
location[] query Represents a buffer, region, or custom polygon specification. Accepts the Location model (as a Buffer, Region, or Custom Polygon) formatted as a JSON string. Multiple location query parameters are allowed. NOTE: When requesting multiple locations, you must include brackets(i.e. ?location[]=...&location[]=...). If not included, only the last location will be used. Yes array
opts query Container for query options. Format as JSON string. No object
groups query Groups (layers) to include. If not specified, all insight groups are returned. See /insights/schema for a list of groups for each insight. No array
periods query Time periods if not using startdate and enddate. Requires format YR{yr}Q{q}. See /insights/schema for a list of periods for a given insight. No array
startdate query Only data later than this date is returned. No date
enddate query Only data before this date is returned. No date

Responses

Code Description
200 List of insight results for each location requested and in the order provided.
400 Client error (probably invalid parameters).
401 Invalid API key.
500 Internal server error.

Geometries API

Geometry querying and management.

GeoJSON Location

GET

Get Location Details

url = "https://idealgeo.com/api/v1/geometries/geometry"

location ={
  "type":"region",
  "regiontype": "zipcode",
  "region_id": "78702"
}

headers = {
    "accept": "application/json",
    "api_key": API_KEY
}

params = {
    "location[]": json.dumps(location),
}

r = requests.get(url=url, params=params, headers=headers)
r.json()

Description: Fetch location GeoJSON

HTTP Request

GET /api/v1/geometries/geometry

Parameters

Name Located in Description Required Type
api_key header Access token. Yes string
location[] query Represents a buffer, region, or custom polygon specification. Accepts the Location model (as a Buffer, Region, or Custom Polygon) formatted as a JSON string. Multiple location query parameters are allowed. NOTE: When requesting multiple locations, you must include brackets(i.e. ?location[]=...&location[]=...). If not included, only the last location will be used. Yes array

Responses

Code Description
200 GeoJSON FeatureCollection
400 Client error (probably invalid parameters).
401 Invalid API key.
500 Internal server error.

POST

Description: Create a custom GeoJSON polygon. Note that this is not supported for general use.

HTTP Request

POST /api/v1/geometries/geometry

Parameters

Name Located in Description Required Type
api_key header Access token. Yes string
body body GeoJSON polygon and properties to save as custom polygon. Yes

Responses

Code Description
200 ID of newly created custom polygon.
400 Client error (probably invalid parameters).
401 Invalid API key.
500 Internal server error.

Region Polygons

GET

Description: For given latitude and longitude, find intersecting administrative regions. Region polygons are simplified for web mapping.

HTTP Request

GET /api/v1/geometries/regions/intersecting/{latitude}/{longitude}

Parameters

Name Located in Description Required Type
api_key header Access token. Yes string
latitude path Search coordinate latitude Yes string
longitude path Search coordinate longitude Yes string

Responses

Code Description
200 GeoJSON FeatureCollection containing polygons and metadata of intersecting administrative regions
400 Client error (probably invalid parameters).
401 Invalid API key.
500 Internal server error.

Traffic API

Vehicle Traffic

Nearest Road Segments

GET

# Get Nearest Segments
url = "https://idealgeo.com/api/v1/traffic/roads/nearest/%s/%s" \
    % (30.25961599997845, -97.73673200028156)


headers = {
    "accept": "application/json",
    "api_key": API_KEY
}

r = requests.get(url=url, headers=headers)
r.json()

Description: For given latitude and longitude, find n nearest road segments

HTTP Request

GET /api/v1/traffic/roads/nearest/{latitude}/{longitude}

Parameters

Name Located in Description Required Type
api_key header Access token. Yes string
latitude path Search coordinate latitude Yes string
longitude path Search coordinate longitude Yes string
n query Number of road segments to return (between 1 and 20) No string (int)

Responses

Code Description
200 GeoJSON FeatureCollection containing n nearest road segments and associated properties
400 Client error (probably invalid parameters).
401 Invalid API key.
500 Internal server error.

Traffic Counts

GET

# Get Traffic Count
url = "https://idealgeo.com/api/v1/traffic/counts/1595402118"

headers = {
    "accept": "application/json",
    "api_key": API_KEY
}

r = requests.get(url=url, headers=headers)
r.json()

Description: Time of day, day of week, and side of street vehicle traffic counts.

HTTP Request

GET /api/v1/traffic/counts/{segment_id}

Parameters

Name Located in Description Required Type
api_key header Access token. Yes string
segment_id path Road segment ID Yes string

Responses

Code Description
200 Vehicle traffic counts as JSON
400 Client error (probably invalid parameters).
401 Invalid API key.
500 Internal server error.

Errors

The API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
cURL Python Elixir