API Reference

Use Radar APIs as building blocks for location-based products and services like pickup and delivery tracking, location-triggered notifications, location verification, store locators, address autocomplete, and more. Or, use Radar APIs to manage your Radar data, including users, geofences, and events.

The API is RESTful, with predictable, resource-oriented URLs. All responses, including errors, return JSON. POST and PUT request body parameters may be sent as application/json or application/x-www-form-urlencoded.

Authentication#

All requests must be authenticated. Authenticate using your API keys, found on the Settings page. Include your API key in the Authorization header.

API endpoints with authentication level Publishable are safe to call client-side (e.g., from the SDK). You should use your publishable API keys to call these endpoints. Use your Test Publishable key for testing and non-production environments. Use your Live Publishable key for production environments.

API endpoints with authentication level Secret are only safe to call server-side. You should use your secret API keys to call these endpoints. Use your Test Secret key for testing and non-production environments. Use your Live Secret key for production environments. Include your API key in the Authorization header.

Sample request#

curl https://api.radar.io/v1/users \  -H "Authorization: prj_live_sk_..."

Errors#

The API uses standard HTTP response codes.

Response codes#

200: Success
202: Accepted
400: Bad request (missing or invalid params)
401: Unauthorized (invalid API key)
402: Payment required (organization disabled or usage exceeded)
403: Forbidden (insufficient permissions)
404: Not found
409: Conflict
429: Too many requests (rate limit exceeded, no state change, or selective throttling)
451: Unavailable for legal reasons (country blocklisted)
500: Internal server error
503: Service temporarily unavailable

Sample error response#

{  "meta": {    "code": 400,    "param": "latitude",    "message": "latitude: Invalid latitude. Valid range: [-90, 90]."  }}

Building blocks#

Use these endpoints as building blocks for location-based products and services like delivery tracking, store locators, address autocomplete, location-based content and notifications, and more.

Track#

Tracks a location update. Returns the user and the events generated, depending on project settings.

On iOS and Android, use the SDK to track user locations in the foreground or in the background.

deviceId is used to identify logged out users. userId and deviceId are used to identify logged in users. If a matching user already exists, it will be updated. If not, a new user will be created.

Do not send any PII, like names, email addresses, or publicly available IDs, for userId. See privacy best practices for more information.

This endpoint is stateful. For anonymous or stateless context, call the context endpoint instead.

Definition#

POST https://api.radar.io/v1/track

Body parameters#

deviceId (string, required): A device ID for the user. Used to identify logged out users.
userId (string, optional): A stable unique ID for the user. Used with deviceId to identify logged in users. Not required for logged out users.
latitude (number, required): The user's current latitude. A number between -90 and 90.
longitude (number, required): The user's current longitude. A number between -180 and 180.
accuracy (number, required): The accuracy of the user's current latitude and longitude, in meters. A number greater than 0. Used when evaluating the confidence of geofence events.
foreground (boolean, optional): true if the client is in the foreground, false if the client is in the background.
stopped (boolean, optional): true if the user is stopped, false if the user is moving.
description (string, optional): An optional description for the user, displayed in the dashboard.
metadata (dictionary, optional): An optional dictionary of custom metadata for the user. Up to 32 keys and values of type string, boolean, or number.
deviceType (string, optional): The user's device type, one of iOS, Android, or Web.
updatedAt (datetime, optional): The client timestamp or historical timestamp when the user's location was updated. Historical data must be upserted in chronological order. Optional, defaults to the current server timestamp if not provided or not in chronological order. A date or valid ISO date string.
replayed (boolean, optional): true if the location is replayed, false if the location is not replayed. Defaults to false.
deviceOS (string, optional): The operating system of the device.
deviceMake (string, optional): The manufacturer of the device.
deviceModel (string, optional): The model of the device.

Authentication level#

Publishable

Rate limits#

1 request per second per device, 180 requests per hour per device, and 1,000 requests per day per device

Sample request#

curl "https://api.radar.io/v1/track" \  -H "Authorization: prj_live_pk_..." \  -X POST \  -d "deviceId=C305F2DB-56DC-404F-B6C1-BC52F0B680D8" \  -d "userId=1" \  -d "latitude=40.78382" \  -d "longitude=-73.97536" \  -d "accuracy=65"

Sample response#

{  "meta": {    "code": 200  },  "events": [    {      "_id": "56db1f4613012711002229f6",      "type": "user.entered_geofence",      "createdAt": "2018-06-12T13:44:10.535Z",      "live": true,      "user": {        "userId": "1",        "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",        "metadata": {          "customId": "abc",          "customFlag": false        }      },      "geofence": {        "tag": "store",        "externalId": "123",        "description": "Store #123",        "metadata": {          "parking": false        }      },      "location": {        "type": "Point",        "coordinates": [          -73.977797,          40.783826        ]      },      "locationAccuracy": 5,      "confidence": 3    },    {      "_id": "56db1f4613012711002229f7",      "type": "user.entered_place",      "createdAt": "2018-06-12T13:44:10.535Z",      "live": true,      "user": {        "_id": "56db1f4613012711002229f4",        "userId": "1",        "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",        "metadata": {          "customId": "abc",          "customFlag": false        }      },      "place": {        "name": "Starbucks",        "chain": {          "name": "Starbucks",          "slug": "starbucks",          "externalId": "123",          "metadata": {            "customFlag": true          }        },        "categories": [          "food-beverage",          "coffee-shop"        ],        "location": {          "type": "Point",          "coordinates": [            -73.977797,            40.783826          ]        }      },      "location": {        "type": "Point",        "coordinates": [          -73.977797,          40.783826        ]      },      "locationAccuracy": 5,      "confidence": 2    }  ],  "user": {    "_id": "56db1f4613012711002229f4",    "live": true,    "userId": "1",    "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",    "metadata": {      "customId": "abc",      "customFlag": false    },    "updatedAt": "2018-06-12T13:44:10.535Z",    "createdAt": "2018-06-10T11:23:58.741Z",    "location": {      "type": "Point",      "coordinates": [        -73.977797,        40.783826      ]    },    "locationAccuracy": 5,    "stopped": true,    "foreground": false,    "deviceType": "iOS",    "ip": "173.14.0.1",    "geofences": [      {        "tag": "store",        "externalId": "123",        "description": "Store #123",        "metadata": {          "parking": false        }      }    ],    "place": {      "name": "Starbucks",      "chain": {        "name": "Starbucks",        "slug": "starbucks"      },      "categories": [        "food-beverage",        "coffee-shop"      ],      "location": {        "type": "Point",        "coordinates": [          -73.977797,          40.783826        ]      }    },    "country": {      "code": "US",      "name": "United States",      "flag": "🇺🇸"    },    "state": {      "code": "MD",      "name": "Maryland"    },    "dma": {      "code": "26",      "name": "Baltimore"    },    "postalCode": {      "code": "21014",      "name": "21014"    },    "beacons": [      {        "type": "ibeacon",        "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d",        "major": "100",        "minor": "1",        "description": "Store #123 - Register #1",        "tag": "store-register",        "externalId": "123-1",        "enabled": true      }    ],    "fraud": {      "verified": true,      "passed": false,      "bypassed": false,      "blocked": false,      "mocked": true,      "jumped": false,      "compromised": false,      "inaccurate": false,      "proxy": false,      "sharing": false      "lastMockedAt": "2023-07-27T17:18:28.536Z",      "lastJumpedAt": "2023-07-27T17:18:28.536Z",      "lastCompromisedAt": null,      "lastInaccurateAt": null,      "lastProxyAt": null,      "lastSharingAt": null    },    "segments": [      {        "description": "Starbucks Visitors",        "externalId": "starbucks-visitors"      }    ],    "topChains": [      {        "name": "Starbucks",        "slug": "starbucks",        "externalId": "123"      },      {        "name": "Walmart",        "slug": "walmart",        "externalId": "456"      }    ],    "fraud": {      "proxy": false,      "mocked": false    }  }}

Context#

Gets context for a location, depending on project settings.

This endpoint is anonymous by default and stateless. For stateful context, call the track endpoint instead.

Definitions#

GET https://api.radar.io/v1/context

Query parameters#

coordinates (string, required): The coordinates. A string in the format latitude,longitude.
userId (string, optional): A stable unique ID for the user. Required for MTU-based pricing.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/context?coordinates=40.78382,-73.97536" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "context": {    "geofences": [      {        "tag": "store",        "externalId": "123",        "description": "Store #123",        "metadata": {          "parking": false        }      }    ],    "place": {      "name": "Starbucks",      "chain": {        "name": "Starbucks",        "slug": "starbucks"      },      "categories": [        "food-beverage",        "coffee-shop"      ],      "location": {        "type": "Point",        "coordinates": [          -73.977797,          40.783826        ]      }    },    "country": {      "code": "US",      "name": "United States",      "flag": "🇺🇸"    },    "state": {      "code": "MD",      "name": "Maryland"    },    "dma": {      "code": "26",      "name": "Baltimore"    },    "postalCode": {      "code": "21014"    }  }}

Geocoding#

Forward geocode#

Geocodes an address, converting address to coordinates.

This endpoint is best for complete addresses. For partial addresses or place names, call the autocomplete endpoint instead.

Returns a confidence level, as defined below:

exact: The result matches the query sent.
interpolated: A result where there is a record for the street but not the exact building number, so the value is calculated between two known building numbers.
fallback: A result where Radar does not have a matching record and cannot interpolate the results. Radar falls back to the region containing the query.

Definitions#

GET https://api.radar.io/v1/geocode/forward

Query parameters#

query (string, required): The address to geocode.
layers (string, optional): Optional layer filters. A string, comma-separated, including one or more of place, address, intersection, street, neighborhood, postalCode, locality, county, state, country, coarse, and fine. Note that coarse includes all of neighborhood, postalCode, locality, county, state, and country, whereas fine includes all of place, address, intersection, and street. If not provided, results from address and coarse layers will be returned.
country (string, optional): An optional countries filter. A string of comma-separated countries, the unique 2-letter country code.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/geocode/forward?query=20+jay+st+brooklyn+ny" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "addresses": [    {      "latitude": 40.7041,      "longitude": -73.9867,      "geometry": {        "type": "Point",        "coordinates": [-73.9867,40.7041]      },      "country": "United States",      "countryCode": "US",      "countryFlag": "🇺🇸",      "county": "Kings County",      "confidence": "exact",      "borough": "Brooklyn",      "city": "Brooklyn",      "number": "20",      "neighborhood": "DUMBO",      "postalCode": "11201",      "stateCode": "NY",      "state": "New York",      "street": "Jay St",      "layer": "address",      "formattedAddress": "20 Jay St, Brooklyn, New York, NY 11201 USA",      "addressLabel": "20 Jay St"    }  ]}

Reverse geocode#

Reverse geocodes a location, converting coordinates to address.

Definitions#

GET https://api.radar.io/v1/geocode/reverse

Query parameters#

coordinates (string, required): The coordinates to reverse geocode. A string in the format latitude,longitude.
layers (string, optional): Optional layer filters. A string, comma-separated, including one or more of place, address, intersection, street, neighborhood, locality, county, state, country, coarse, and fine. Note that coarse includes all of neighborhood, locality, county, state, and country, whereas fine includes all of place, address, intersection, and street. If not provided, results from all layers will be returned.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/geocode/reverse?coordinates=40.70390,-73.98670" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "addresses": [    {      "latitude": 40.70390,      "longitude": -73.98670,      "geometry": {        "type": "Point",        "coordinates": [-73.98670, 40.70390]      },      "addressLabel": "20 Jay Street",      "formattedAddress": "20 Jay Street, Brooklyn, New York, NY 11201 USA",      "country": "United States",      "countryCode": "US",      "countryFlag": "🇺🇸",      "state": "New York",      "stateCode": "NY",      "postalCode": "11201",      "city": "New York",      "borough": "Brooklyn",      "county": "Kings County",      "neighborhood": "DUMBO",      "number": "20",      "distance": 5,      "layer": "address"    }  ]}

IP geocode#

Geocodes the requester's IP, converting IP address to city, state, and country.

Definitions#

GET https://api.radar.io/v1/geocode/ip

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/geocode/ip" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "address": {    "latitude": 40.70390,    "longitude": -73.98670,    "geometry": {      "type": "Point",      "coordinates": [-73.98670, 40.70390]    },    "country": "United States",    "countryCode": "US",    "countryFlag": "🇺🇸",    "state": "New York",    "stateCode": "NY",    "postalCode": "11201",    "city": "New York"  },  "proxy": false,  "ip": "107.77.199.117"}

Search#

Autocomplete#

Autocompletes partial addresses and place names, sorted by relevance.

Definitions#

GET https://api.radar.io/v1/search/autocomplete

Query parameters#

query (string, required): The partial address or place name to autocomplete.
near (string, optional): The location to search. A string in the format latitude,longitude. If not provided, the request IP address will be used to anchor the search.
layers (string, optional): Optional layer filters. A string, comma-separated, including one or more of place, address, intersection, street, neighborhood, postalCode, locality, county, state, country, coarse, and fine. Note that coarse includes all of neighborhood, postalCode, locality, county, state, and country, whereas fine includes all of place, address, intersection, and street. If not provided, results from address and coarse layers will be returned.
limit (number, optional): The max number of addresses to return. A number between 1 and 100. Defaults to 10.
country (string, optional): An optional countries filter. A string of comma-separated countries, the unique 2-letter country code.
expandUnits (boolean, optional): If true, separate results will be returned for units within buildings. Only available for layers="address" and for the countries US and CA. Defaults to false.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/search/autocomplete?query=brooklyn+roasting&near=40.70390,-73.98670" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "addresses": [    {      "latitude": 40.695779,      "longitude": -73.991489,      "geometry": {        "type": "Point",        "coordinates": [-73.991489,40.695779]      },      "country": "United States",      "countryCode": "US",      "countryFlag": "🇺🇸",      "county": "Kings County",      "distance": 990,      "borough": "Brooklyn",      "city": "Brooklyn",      "number": "1",      "neighborhood": "Brooklyn Heights",      "postalCode": "11201",      "stateCode": "NY",      "state": "New York",      "street": "Clinton St",      "layer": "place",      "formattedAddress": "1 Clinton St, Brooklyn, New York, NY 11201 USA",      "placeLabel": "Brooklyn Roasting Company"    }  ]}

Search users#

Searches for users near a location, sorted by distance.

Definitions#

GET https://api.radar.io/v1/search/users

Query parameters#

near (string, required): A location for the search. A string in the format latitude,longitude.
radius (number, optional): The radius to search, in meters. A number between 100 and 10000. Defaults to 1000. If mode is specified, the radius is the travel duration in minutes.
mode (string, optional): The travel mode. A string, one of car, truck, foot, or bike.
metadata[key] (string, optional): Optional metadata filters. Values may be of type string. Type will be automatically inferred. For example, to match on working == true, use &metadata[working]=true.
limit (number, optional): The max number of users to return. A number between 1 and 100. Defaults to 10.

Authentication level#

Secret

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/search/users?near=40.78382,-73.97536&radius=1000&limit=10" \  -H "Authorization: prj_live_sk_..."

Sample response#

{  "meta": {    "code": 200  },  "users": [    {      "_id": "56db1f4613012711002229f4",      "live": true,      "userId": "1",      "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",      ...    },    ...  ]}

Search geofences#

Searches for geofences near a location, sorted by distance.

Definitions#

GET https://api.radar.io/v1/search/geofences

Query parameters#

tags (string, optional): Optional tag filters. A string, comma-separated.
metadata[key] (string, optional): Optional metadata filters. Values may be of type string. Type will be automatically inferred. For example, to match on offers == true, use &metadata[offers]=true.
near (string, required): A location for the search. A string in the format latitude,longitude.
radius (number, optional): The radius to search, in meters. A number between 100 and 10000. Defaults to 1000.
limit (number, optional): The max number of geofences to return. A number between 1 and 100. Defaults to 10.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/search/geofences?tags=store&metadata[offers]=true&near=40.783826,-73.975363&radius=1000&limit=10" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "geofences": [    {      "_id": "56db1f4613012711002229f5",      "createdAt": "2016-06-10T13:44:10.535Z",      "live": true,      "tag": "store",      "externalId": "123",      "description": "Store #123",      "metadata": {        "rating": "4.5"      },      "geometryCenter": {        "type": "Point",        "coordinates": [-73.97536, 40.78382]      },      ...    },    ...  ]}

Search places#

Searches for places near a location, sorted by distance.

Definitions#

GET https://api.radar.io/v1/search/places

Query parameters#

chains (string, optional): Chain slug filters. A string, comma-separated. If your project has a chain mapping, the mapped ID can be used in place of the chain slug. If not provided, categories must be provided.
categories (string, optional): Category filters. A string, comma-separated. If not provided, chains must be provided.
iataCode (string, optional): The 3-letter IATA code for the airport to search. If provided, no other parameters are required.
chainMetadata[key] (optional): Optional chain metadata filters. Values may be of type string, boolean, or number. Type will be automatically inferred. For example, to match on offers == true, use &chainMetadata[offers]=true.
near (string, required): A location for the search. A string in the format latitude,longitude.
radius (number, optional): The radius to search, in meters. A number between 100 and 10000. Defaults to 1000.
limit (number, optional): The max number of places to return. A number between 1 and 100. Defaults to 10.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/search/places?chains=starbucks&near=40.78382,-73.97779&radius=1000&limit=10" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "places": [    {      "name": "Starbucks",      "chain": {        "name": "Starbucks",        "slug": "starbucks",        "externalId": "123",        "metadata": {          "customFlag": true        }      },      "categories": [        "food-beverage",        "coffee-shop"      ],      "location": {        "type": "Point",        "coordinates": [          -73.97779,          40.78382        ]      }    },    ...  ]}

Validate an address#

Validates an address. Currently only available for US and Canada addresses.

This endpoint is best for validating complete structured addresses. For partial addresses or place names, call the autocomplete endpoint instead.

Returns a verificationStatus as part of the result, as defined below:

verified: The input has a complete and unique match with a result.
partially verified: The input has a partial match with a result.
ambiguous: The input closely matches multiple results.
unverified: Unable to verify the input address.

Returns a recordType value in the metadata field as part of the result, values are defined below according to USPS standards:

S: Street Address
P: Post Office Box
R: Rural Route
H: High-rise
F: Firm
G: General Delivery

Definitions#

GET https://api.radar.io/v1/addresses/validate

Query parameters#

city (string, required): The city name.
stateCode (string, required): The 2-letter state abbreviation (e.g., NY).
postalCode (string, required): The postal or zip code. Plus 4 codes are accepted but not required.
countryCode (string, required): The unique 2-letter country code (e.g., US).
number (string, optional): The building or P.O. box number. If not provided, addressLabel must be provided.
street (string, optional): The street name. If not provided, addressLabel must be provided.
unit (string, optional): The unit number, such as apartment or suite (e.g., Apt 3).
addressLabel (string, optional): The first line of the address, including the building number, street name, and unit number if applicable (e.g., 20 Jay St Apt 3). If not provided, number and street must be provided.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/addresses/validate?countryCode=US&stateCode=NY&city=New%20York&number=841&postalCode=10003&street=Broadway&unit=Fl%7" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "address": {    "addressLabel": "841 BROADWAY FL 7",    "unit": "FL 7",    "number": "841",    "street": "BROADWAY",    "city": "NEW YORK",    "stateCode": "NY",    "postalCode": "10003",    "plus4": "4704",    "county": "NEW YORK",    "countryCode": "US",    "formattedAddress": "841 BROADWAY FL 7, NEW YORK, NY 10003-4704 US",    "metadata": {      "recordType": "H",      "propertyType": "commercial"    }  },  "result": {    "verificationStatus": "verified"  }}

Routing#

Distance#

Calculates the travel distance and duration between an origin and a destination.

Definitions#

GET https://api.radar.io/v1/route/distance

Query parameters#

origin (string, required): The origin. A string in the format latitude,longitude.
destination (string, required): The destination. A string in the format latitude,longitude.
modes (string, required): The travel modes. A string, comma-separated, including one or more of car, truck, foot, or bike.
units (string, optional): The distance units. A string, metric or imperial. Defaults to imperial if not provided.
avoid (string, optional): The features that calculated routes should avoid. A string, comma-separated, including one or more of tolls, highways and ferries. No features are avoided if not provided.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/route/distance?origin=40.78382,-73.97536&destination=40.70390,-73.98690&modes=foot,car&units=imperial" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "routes": {    "geodesic": {      "distance": {        "value": 29333.03,        "text": "5.6 mi"      }    },    "foot": {      "distance": {        "value": 54596.46,        "text": "10.3 mi",      },      "duration": {        "value": 98.48,        "text": "1 hr 38 min"      }    },    "car": {      "distance": {        "value": 42480.31,        "text": "8.0 mi"      },      "duration": {        "value": 19.9,        "text": "20 mins"      }    }  }}

Matrix#

Calculates the travel distances and durations between multiple origins and destinations for up to 100 routes.

Definitions#

GET https://api.radar.io/v1/route/matrix

Query parameters#

origins (string, required): A list of origins. A pipe-delimited string in the format latitude0,longitude0|latitude1,longitude1|....
destinations (string, required): A list of destinations. A pipe-delimited string in the format latitude0,longitude0|latitude1,longitude1|....
mode (string, required): The travel mode. A string, one of car, truck, foot, or bike.
units (string, optional): The distance units. A string, metric or imperial. Defaults to imperial if not provided.
avoid (string, optional): The features that calculated routes should avoid. A string, comma-separated, including one or more of tolls, highways and ferries. No features are avoided if not provided.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/route/matrix?origins=40.78382,-73.97536&destinations=40.70390,-73.98690|40.73237,-73.94884&mode=car&units=imperial" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "origins": [    {      "latitude": 40.78382,      "longitude": -73.97536    }  ],  "destinations": [    {      "latitude": 40.70390,      "longitude": -73.98670    },    {      "latitude": 40.73237,      "longitude": -73.94884    }  ],  "matrix": [    [      {        "distance": {          "value": 42480.31,          "text": "8.0 mi"        },        "duration": {          "value": 19.9,          "text": "20 mins"        },        "originIndex": 0,        "destinationIndex": 0      },      {        "distance": {          "value": 31108.92,          "text": "5.8 mi"        },        "duration": {          "value": 17.13,          "text": "17 mins"        },        "originIndex": 0,        "destinationIndex": 1      }    ]  ]}

Route match#

Snaps points collected along a route to roads that were most likely traveled on. Returns the matched path and road information.

For best results, the sample rate should be less than 10 seconds between points.

Definitions#

GET https://api.radar.io/v1/route/match

Query parameters#

path (string, required): A list of up to 100 coordinates along a route to be snapped. A string in the format latitude1,longitude1|latitude2,longitude2.
mode (string, optional): The travel mode. A string, one of car, truck, foot, or bike. Defaults to car.
roadAttributes (string, optional): Attributes of matched roads to be included in the response. A string, comma-separated, including one or more of speedLimit, names, and roadClass.
- roadClass return values will be one of:
  - motorway
  - trunk
  - primary
  - secondary
  - tertiary
  - unclassified
  - residential
  - service_other
units (string, optional): The distance and speed units. A string, metric or imperial. Defaults to imperial if not provided.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/route/match?path=40.73421259605101,-73.98635368448336|40.73615136186456,-73.98534685613593|40.73616535996882,-73.98026652961276|40.73701616007588,-73.98238510730718&mode=car&roadAttributes=names, speedLimit, roadClass" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200,  },  "matchedPath": [    {      "latitude": 40.734251,      "longitude": -73.990903,      "originalIndex": 0    },    {      "latitude": 40.734442,      "longitude": -73.992048,      "originalIndex": 1    },    {      "latitude": 40.734847,      "longitude": -73.994474,      "originalIndex": 2    }  ],  "roadAttributes": [    {      "names": [        "Broadway"      ],      "speedLimit": {        "value": 25,        "text": "25 mph"      },      "roadClass": "secondary",      "originalIndex": 0    },    {      "names": [        "East 13th Street"      ],      "speedLimit": {        "value": 25,        "text": "25 mph"      },      "roadClass": "residential",      "originalIndex": 1    },    {      "names": [        "5th Avenue"      ],      "speedLimit": {        "value": 25,        "text": "25 mph"      },      "roadClass": "secondary",      "originalIndex": 2    }  ],  "geometry": {      "polyline": "uafulAln`clCpKzAhCFqAbEs\\heAaA|CuAlEgj@teBm@jBs@|BbBjA~XzR",  }}

Directions#

Calculates the most efficient route between two or more locations to visit in order.

Definitions#

GET https://api.radar.io/v1/route/directions

Query parameters#

locations (string, required): A list of up to 25 coordinates to visit in order. A pipe-delimited string in the format latitude0,longitude0|latitude1,longitude1|....
mode (string, optional): The travel mode. A string, one of car, truck, foot, or bike. Defaults to car.
units (string, optional): The distance units. A string, metric or imperial. Defaults to imperial.
avoid (string, optional): The features that calculated routes should avoid. A string, comma-separated, including one or more of tolls, highways and ferries. No features are avoided if not provided.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/route/directions?locations=40.734250,-73.990934|40.712971,-73.951385|40.745580,-73.903162|40.774419,-73.872746&mode=car&units=imperial" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "routes": [    {      "duration": {        "value": 26.882683333333333,        "text": "27 mins"      },      "distance": {        "value": 59576.77356,        "text": "11.3 mi"      },      "legs": [        {          "startLocation": {            "latitude": 40.73425,            "longitude": -73.990934          },          "endLocation": {            "latitude": 40.712971,            "longitude": -73.951385          },          "duration": {            "value": 9.53685,            "text": "10 mins"          },          "distance": {            "value": 19924.54132,            "text": "3.8 mi"          },          "geometry": {            "polyline": "kafulAnn`clCfKxAhCF`CJdg@vGtB\\|BZpf@`HhC^dBThMdBnTtCp@TnBp@`ClAZPhZnUzBdB`BtAl\\zWxAjAlBzA|UjRfEhD`ClBhRfOlCxBjBxAhBxAxKzItNhL|BhBnB|Af]rXnB~A|AnAn[fWbAv@~ArAzBfBxStPbInGtB`BlBzA~b@l]bAx@d@\\hBxAjMdKTPxGlFnJvH|StPnCxBhFbEr@{EfEeYvCyRf@kD\\{BBUtC}RfAoFbAcFpDsNl@_Cl@aCfLcd@r@sCn@cC`Lsc@p@kCl@aCjE}P`E}Od@iBz@{DrD`A|JxCxWdFxc@fLzIzBzL~C~Bj@dAXlg@rM~Ab@pA^|`@pLp@RtBl@bBf@xEpAjQ`FtBl@xF~AfAwEzBoCpAyAtE}TvGs[fAkFxAiHpG{Zh@qCR{@f@cCr@iDrKmh@VoAh@gCb@wBfJ{c@\\aBr@iD~AeIv@yDp@wChEuSf@eCj@kCfGeZpBoJf@gCh@iC`G_ZvBuJhAsFnAmFvJyd@f@{BvP}l@t@cDr@sCrK{_@bBgG\\sAXmAp\\}`B~J_g@|\\gcBpb@_uB|U{kAdIcTdVqpAl~DssRj_@{hB|Fq_@zt@opDtG_UrEcU`AoFjCkOd@yC`@}CToCTwChAeTx@}PRkCb@eDd@gCn@sCrP_r@\\uAjAuEmCuAsP}I}KsG}@i@kAq@QeFo@uTAMiBy_@wBac@KkBMsBSaDk@mIs@{Io@aMmBs]{AmXS}EQ{CoBac@OeDeA{ScAoTUmEUeEsA{X}@yPoEi~@WkF}AcPScFG}AUkFaDXm[fCgKv@aCRec@hD_CP{CZq]bD"          }        },        {          "startLocation": {            "latitude": 40.712971,            "longitude": -73.951385          },          "endLocation": {            "latitude": 40.74558,            "longitude": -73.903162          },          "duration": {            "value": 11.365883333333333,            "text": "11 mins"          },          "distance": {            "value": 22516.40492,            "text": "4.3 mi"          },          "geometry": {            "polyline": "oo|slAfks`lCwGn@}k@pFgIj@wCR{D`@mSbBgBNaYnC_DZqCmDqNaTkt@yhAkKiR}BoDiBeDsZoj@oY}f@cBaDqBkDsVyc@y^mo@_B_DqAkCsJeRuKiT_Usa@eB_DcBsCad@e{@gCmHcLvHqB~A{D`Aa@JmBtAq@f@mJvIaJ~J_AdAcClCIJq[f]eAnAwEbFeAvA{BhC}BnCmCpCaRnT_AdA{HrIkB|Bq@x@{LbNwFlG{ClCkBxA}ApAs@^_SfKoXtMgPrHqUfLkTrKcA`@yB|@qCpAa@PsJpEkSvJ}N`HsFhCk@VuLrFwDdBq@\\oMfGiAh@qB`AsCxAq@^k^|PyNxGwHrDyE~BkGvC}HrDgKzEsB|@kCjAoSzJaSrJiObHgBx@}BdAq@Z}WlMyG~CwG~Cw@^qEvBq\\|O}CzAQqEmAoW{@{QyBmf@{@wQ{@iSIwBI{CMwDcAeVc@oK_AqPm@iFqDiPe^guAsAeFuIe\\sHiYsSkw@wNil@a@{AiAyEq@mCoJ_`@uAgMm@sFyDkf@k@uGa@cEm@_Fs@uFaAsGgAeGiAaGsA}F{AaGyFuT}Lme@mGgVaB}FgBwFqBoFyBwFyDsJuMm\\}JuVyE{DGiNuJmVs@oBo@aBk@gBeQ}o@eBsG_AwCeAgDmDaNaXscAeAkD{@qCeSku@oPan@oD}MuCkJsA{DcKmZeKmZaBmEgAcDgOyc@}@eDwAmEoBgG]_AiEcM_GgQqAkFs@_D_HyUgCwIgAwDgBcGoQkn@wAmEmA_EmKy^_@uA_CqIi@mB{AmFiB}F_Vus@gBaFuA_EyUis@eB}E}AoEkNeb@iBoF_CaHeEeMaUaq@sAgFkA}DmUyq@oB_GyBgGsR_j@i@yAsDwJ}CkKm@gBuQsj@eAgDeA{CuGuRwAcFaHcZw@sDk@gCgOqt@s@}Di@uC{Ima@i@mCuCsN_C}HaJea@gEqUqRq~@eDoOsD}P_He[mMsp@wAmHmFkXaR}{@_Paz@kKa|@aJg|@U}Da@cDyGap@k@uFkA{I{@oK[kHMaO?}FHqF@yM@yj@uE{dAqEkaAi@yK"          }        },        {          "startLocation": {            "latitude": 40.74558,            "longitude": -73.903162          },          "endLocation": {            "latitude": 40.774419,            "longitude": -73.872746          },          "duration": {            "value": 5.979916666666667,            "text": "6 mins"          },          "distance": {            "value": 17135.82732,            "text": "3.2 mi"          },          "geometry": {            "polyline": "oh|ulAbcu}kCuEy`AeEy~@{Ea`AwEe`AkBg^sAcX{Dkv@}Dew@wC\\ea@vEwAPgBTub@`Fuk@rGODmD~@M}Cc@{Ke@}IoAqC_AaBeAy@kAm@oBg@s@UiAQcA?s@L_@D_AZaAXu@\\qG~Cyg@xWgHjDoI|D}G~CeGnCaDfA{DhAaE`AiEx@sNzFsHl@aVnAm_@nD}ShDaQ`EiQfIs~@vg@mc@|V}CfBkZbJaa@pM_UlGwWpFkGxAe^|GkS`BaMz@qLQuM{@wQeDwM}DeNeFqQkGwg@q[e^_Ti_C}wA}l@i`@sE_DuDsCsDaDyDeEwCkDuCyD_DwEkLqRmCwDuDuEoDeE{CuC{CoC}EkDaAm@wBsAmF_CuDcAwEuAyQkEoEuAsDoAeD}A}CsBkCsByCyC}DqEiCyD}BsEuBwEeBmFkAkEeAaFs@_Gg@kG[sFSsHaAyh@c@eRm@cRcCyl@kAcVqIqs@{A_Q_B{PaBgPgBwPmBoPuBkPwBcPiCoQsBuMeCwOoC}OyCiPqCyO{C_PcDaPcDsOiDoOqDoOuDkO_EqOiEaOcEaOoE_OuE_O}E{N{EqNgFkN}Va}@mHuRcHkQqFaNaF}MyGiQgLkZaGqVm@sBq@kCmAaGoAyGgAiH_A{Gw@cH_@}EiEyy@wGesA]mJEqEuAKmWwAuJa@_F@oDPgB\\eBj@{D~@}C`As@LqQlCwDl@yB\\cBTyEn@mVdFwBr@{B~@yCfBqEvDkElEcCxCqBpCyCeDkCiDqAqBmAoBaAsB}@mB{@{Bw@aCw@sCwBqJm@oCZgALMqA}GUmBg@yAkA}LmFin@eIe}@gByA_ET??"          }        }      ]    }  ]}

Optimize route#

Calculates the optimal ordering and route to visit a list of locations.

Definitions#

GET https://api.radar.io/v1/route/optimize

Query parameters#

locations (string, required): A list of up to 10 coordinates to visit. A pipe-delimited string in the format latitude0,longitude0|latitude1,longitude1|.... The first location should be the origin of the route, and the last location should be the final destination.
mode (string, optional): The travel mode. A string, one of car, truck, foot, or bike. Defaults to car.
units (string, optional): The distance units. A string, metric or imperial. Defaults to imperial.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/route/optimize?locations=40.7343164,-73.995688|40.6396701,-73.9257626|40.6390023,-73.9975035|40.7227423,-73.9983234|40.6410279,-73.7746107&mode=car&units=imperial" \  -H "Authorization: prj_live_pk_..."

Sample response#

{  "meta": {    "code": 200  },  "route": {    "distance": {      "value": 137388.45584,      "text": "26.0 mi"    },    "duration": {      "value": 49.1802166667,      "text": "49 mins"    },    "legs": [      {        "startLocation": {          "latitude": 40.7343164,          "longitude": -73.995688        },        "endLocation": {          "latitude": 40.7227423,          "longitude": -73.9983234        },        "startIndex": 0,        "endIndex": 3,        "distance": {          "value": 9137.1394,          "text": "1.7 mi"        },        "duration": {          "value": 5.2633833333333335,          "text": "5 mins"        },        "geometry": {          "polyline": "kefulAxyiclCg_AlxCiBzFmBjGa}@`uC_AxCsAhEeBvEhJrEd^fQj@XfClAvAr@lHlD~BlAfFfClCpAtLjG~Av@vBfAp[lOpI`EjB|@tBbAdF`CtIbE`JfEjD`BhBz@lCnAlEtB|L|FnB~@xCvA|SzJ~E~BfK~EvJtE`Ab@~@d@fFbCjNvGl]lPlKbFxCvAdBx@bPvHhD`B~At@tPdIdCjAlBbAr\\lQdNvFhDvAvBXjEj@d[dChJt@dBNhCN~CNl_@zCjCTXsGzJc{BZgHmC{@oOwEmEsFaDaB}@eAe@yA\\gDvA_FvHsR~@aC~@cCjH}QzH_Sv@sBjAuChRef@`AeC|@}BhP}a@rAmDtAqD~Tkk@jTkj@`AcC|@_CzG}PxHwRbAkCnAaDjNg^bBqHBG~@mFfCrB~LzJvq@zi@xAjAbAx@fM`Kpw@xn@|AnAjAmDFShJ_Z"        }      },      {        "startLocation": {          "latitude": 40.7227423,          "longitude": -73.9983234        },        "endLocation": {          "latitude": 40.6390023,          "longitude": -73.9975035        },        "startIndex": 3,        "endIndex": 2,        "distance": {          "value": 44586.6156,          "text": "8.4 mi"        },        "duration": {          "value": 15.074816666666667,          "text": "15 mins"        },        "geometry": {          "polyline": "{uotlAt{nclCjEeNt@aCh@aBdQci@hBwFnApFre@h]`CdBnAqFbCcKn@oCj@aClM{i@FUf@yBl@eCjMwi@p@sCh@yBtLug@DQh@}Bh@yBDQjLmf@h@}BFW`AaEjEjAtIbCxGMzWjIlCz@fBj@ju@nUnCz@bC|@LFvRnIfUpJlV~KtBbAlB~@hc@tUhR|J|DrBzDAbBOvAWjAg@|Y{PfHsF`B}AhBsBfByBnFkH|AiBzAeBzAcB|A{AdB}ApBwAhCyAbCqAtVqKzq[o~N`UoK|@a@rNaDtCcA|Bi@pCYnAKbBLxAb@rAbA~@pA`AzAt@tB\\lCJtCClCYvBg@nBw@~AkAnAqAlAmLnAgFKmIOmg@kAyDh@BcBd@oYHsDB{ANoJr@_[`Cu`@~Bop@z@gGdAiIh@cEv@uGt@yE~@cF`A_Ez@cDjA}B~@wAbBaBzAaAjA]`B]rA@|AVlA^jAt@x@bAx@bBp@zBT~BC~CQbDg@|BcA~BkLlOoV|Y{PzRcRvTsE`G{EpH{FjKiChFuDfIcCfHwCbJaBfGiBzHgBzIgAhIy@|HqBxSeBnScBzR}Drf@iAnM}Etn@iAfP{Cxk@Y|Qi@nSWjOWfUHfJT|LPvH^xMj@hHdA`Ix@rFpAbIjBhJnB`KrB|IjD|LrJzZnLfZvH~TvL|VhJ`NdL~NzNfMzOvJhVhKtt@xXf`@rNvl@fUrcAt_@hyAxi@da@jNfPhEbRrG~MxDjLpBnMz@vOBhJi@pU{Cld@cOnc@kO~KqC~KeBvLu@lGCjGZlNbClN|DnNpErxMpcFv\\~Nr`@lOdb@lMfPhDzNnAfXa@vSkDjJaDbHaDpIcFrI_Gdx@mr@~V{R`g@g_@fn@ec@z`Li~FtQgJdVgJfTeJjH}AbD}@`D}ArF{DxBoBzBmC|EaH`GiLpIeQhOyX`J{Q~JuQzt@m{A~Ow[no@apAzZyk@tBoD~DsG|CkFvCuEtCaEfFwG`OqPlJ{J~HaHjS{O|dBmhAr[mT`U_ShVoXhPmUtRw\\rS{`@`k@shAvCyFln@g~@lk@}~@`Te\\zCeAbCfCxAxA~XxYfBn@tJu@l{@wIxJkAv]wDto@wHx{@oIpCk@|X}Cx_BkQfEe@xC]pgByRzC[pBrGvAzHj[llAzAlCzBdClCdJjArDnQzn@bXv_AbCnInUpx@dAdDbAlDvA~E`BvF`GbU`h@jhBjGpTlEjOjAxChAnCbGfLpMxUdB`D~ArChGbK~Q~ZdHtL|HzM|IhOtHnMlItNtE|H`BrCnAtBpZ`h@~GnLfJzOpHhMzJvPbQdZlDbGhCjEpHjMpIvNrIzNfChEfNtUlHbMdIdNfIjN|\\xk@cm@dkAeC|Eb]f^|CbDbZ}k@l@kA"        }      },      {        "startLocation": {          "latitude": 40.6390023,          "longitude": -73.9975035        },        "endLocation": {          "latitude": 40.6396701,          "longitude": -73.9257626        },        "startIndex": 2,        "endIndex": 1,        "distance": {          "value": 28047.90116,          "text": "5.3 mi"        },        "duration": {          "value": 13.328916666666666,          "text": "13 mins"        },        "geometry": {          "polyline": "{glolAjcmclCtKaTzBmEaBqC{EgIeIgNwHsM}\\yk@gIkNeIeNmHcMgNuUgCiEsI{NqIwNqHkMiCkEmDcGcQeZ{JwPqHiMgJ{O_HoLqZah@oAuBaBsCuE}HmIuNuHoM}IiO}H{MeHuL_R_[iGcK_BsCeBaDqMyUcGgLiAoCkAyCmEkOkGqTah@khBaGcUaBwFwA_FcAmDeAeDoUqx@cCoIcXw_AoQ{n@kAsDmCeJcDqNm@oD]yC{@aQ[yEoD_q@[uG]oG{@sOgA_TaBcZaB}ZgBc]mEyx@qEyx@mDwr@MmH@mCHqCbBm[FaATqCVkDzAqT|D}k@VoDFuEOyEg@uDaCaJqL}`@kAwD_AgDgDmLuIc[u@uHs@oHsKu_@cV}y@_AaD{@sCoSir@}Rmq@}@{Co@uBoS{r@wRgq@_AaDw@oC{Rqq@iN_e@s@aCwDsMmUax@mIiY}D_N{HsVaWa~@eWu{@}Usy@OuHmE_pBH_I~@oHxQsb@|ByAjB]lJg@|BeAxBuDOsRkA}EC_Fk@qXsDujB{@qb@w@g`@oH}sDu@c_@aEaqBAYy@_a@aAw`@s@wYi@aSc@_Qi@kSsBo{@k@aUc@wQg@_SsBey@g@sRc@oQg@gSsBky@c@mQi@aTi@cTi@aTmAqf@]yMu@wYa@yOuBs{@g@kSi@kTe@{QsBiy@e@}Pi@mSm@mUg@iTe@wRc@sRuBey@e@mQg@qSo@wVi@gVc@kSc@oRyBgy@g@eRi@wSi@qSuBy{@i@eSc@kQg@uRuBo{@i@eTkAqf@[sLG_DGsBa@sOe@mR_Ag[IqCIsCYiJvErArA`@h]vJzZvIrYjIvUxGxTzFdOxDbXhHjRnFhOdE~Ab@pRjFdVdGf_AtWpX`F~CTzDZ`D\\lEd@tJdAtfAfLzJdAfE`@pD^lC\\xGt@bHv@ph@|Ft]pCjQvA|D`@dFf@`QlBzaBdRbPhBvD^hDZvP`A|YfBrkA`M`UnA|SbB"        }      },      {        "startLocation": {          "latitude": 40.6396701,          "longitude": -73.9257626        },        "endLocation": {          "latitude": 40.6410279,          "longitude": -73.7746107        },        "startIndex": 1,        "endIndex": 4,        "distance": {          "value": 55616.79968,          "text": "10.5 mi"        },        "duration": {          "value": 15.5131,          "text": "16 mins"        },        "geometry": {          "polyline": "qjmolAbia_lC}ScBaUoAskAaM}YgBwPaAiD[wD_@cPiB{aBeRaQmBeFg@}Da@kQwAu]qCqh@}FcHw@yGu@mC]qD_@gEa@{JeAufAgLuJeAmEe@aD]{D[_DUqXaFg_AuWeVeGqRkF_Bc@iOeEkRoFcXiHeOyDyT{FwUyGsYkIe`@uUwF}AmP_FqA_@cF{A[gOK_IK_IGwQfAoy@z@iy@BaGHeG^_[j@kh@HwILuH~@es@b@{T`@uTXuTVcWtAamAZ}R?}GPkMV_VXe\\JeLKcXMiM]i[W_U_@uIi@iHiAqNeDwa@_Giu@mD_e@eEii@]oEaDua@aGot@gRq~Bw@mJqA_P_AkLcBgJeDwK}CyHyFcLyI_P_h@o_A{EeH{HeIsSgToFcIaC}H_AaKcB_UiCu]G{@m@}Hc@aHsA_TaDsg@wAgSyDid@oDic@w@sJWyHJsK|@qPnFaq@lEcj@nCi_@PiHKaGa@iFcBmIiCwJsR{l@{P{h@}EeOkDmKsF}PwBuGaCoHq[{`AiJcYc\\wbAgQki@kYs{@{Km\\ea@}nAaJuXi]seA{IiX}J}Z}Tar@aKa[{Yu|@iPke@qBgG{Oef@kCeIePsi@eRek@qKg\\ic@esAuWix@ePch@_\\idAeAsCgE}KeKySyHoO{KsQyKkQmTe\\uQkXyRmYcHcLcDcIiDuMqAeMYuDuBsXa@mFsCc`@_Qi}B_@wE_@}EMiBuHabA{B_ZcCq[gDkc@eC{]_Eok@qDmh@{O_oBeIodAgBkU_CgZ}G_|@sDyh@{Fut@mXukDKqAqC}`@a@kI?uDBoBfa@mdBl\\k`BP_AvFsX~SmdAbHk]vE_c@tFon@|Dm_@tFgZ|Gs]vHa^jAiFfI{^jJm[`L}[zNa]bc@ibArKgX`IqUxHg[vHaYnI}n@p~@uwGtLqeAnGcm@~WsqDlJkoApX_gDtEoi@zBqVpAuNzRapCjf@atIz@sPbAyTXeXYiY{A}[mCwXuDiY}EaVcG_UkHoUgZa{@wNgb@_Lia@yJce@_Hod@}G_k@}BmUo@iHg@cGk@wGg@}Ge@{Gc@kGe@iHa@yGsAecACeE?cEFoDRkD^oDb@gDr@kD`AkDbA{CnAyCvAkC~AcChByBlBqBhB}A|BwA`CkAbC_A`Cs@jCi@jCUdCKnCBrCRhCZzBl@~Bx@pBbAvBpAjBlAhFnD~BzAnCzArCjAvIzC|B`Cna@n^dlAxfArDfDdJfInD`DxDdDrD|CvDxCzDzCrDpCzDtC~DpCxDfCfEhC`EbC|DzBfDjBf@V|DtBzBhAfAh@fErBbEjBlEpBnEjBlEdBjE`BpE`BhExAnExArEtArEpAnElApEfAtEdApE`A`FbApEx@tEx@tEr@pEp@vBVdBRrEh@hAJrCVxE`@xE\\zE\\rETbFTpEN|EJtEHbFDvE@vECbFEzEIxEOtEQvESxEYvE[tE_@|Ee@tEg@`Fk@tEm@xEu@rEs@rEy@xE_AnE_AvEeApEgAtEiApEoAlEoAtEyAlE{AhEyAnE_BpEiBhEgBlEmBbEiBhKcFxKwFdKuFlK_GbK_GfKcG~JeGfKsGzJoG`KwG|JwGzJ}GvJaHxJgHvJmHrJkHlJmHrJ{HlJyHnJ}HdJ_IlJkI`JeIfJoI|IoIdJ}I~IwIxI{IpDsDvIaJxIgJzIuJjIcJpIsJjIyJbIcKzCeEzCsEtCoEfHqLnGsLjGmMxFyMlFeN|EqNlE}N`EiOlDuOhDqPfC}N~BoPjBkP~AuPjAsP|@}Pf@aQNcHHgGDwG@gHEuHC}GKaHQaHQiHy@qYuByv@u@yWe@{Pg@wQ]oLa@{P_@yPwBsxA@{GByGJeHNcHNaHdAsa@PmHL}GFwGBaHAeHEwGKeHQaHSaHY{G]kG[aFKuAi@sGsDoa@yDo]}J}a@kIwVaHkU}Nkd@oNyc@sRgn@_Ogd@sFaOwEqRoAqIUsH`A{LzBwKjEqMpCwFzDoGlFkGlMqLd_@kUfH{EvGeGrE}FxDwJ`AuFz@}IjEqi@d@aFj@iEr@cDv@wClNmd@b@wBZ{BRiCJiCAiCIwC]iDa@sC?A"        }      }    ]  }}

Manage your Radar data#

Use these endpoints to manage your Radar data, including users, geofences, and events.

Users#

A user represents a user tracked in your project. Users can be referenced by Radar _id, userId, or deviceId.

Object fields#

_id (string): A unique ID for the user, provided by Radar. An alphanumeric string.
live (boolean): true if the user was created with your live API key, false if the user was created with your test API key.
userId (string): A stable unique ID for the user.
deviceId (string): A device ID for the user.
description (string): An optional description for the user.
metadata (dictionary): An optional dictionary of custom metadata for the user.
location (point): The user's current location, a Point in GeoJSON format.
locationAccuracy (number): The accuracy of the user's current location in meters.
foreground (boolean): true if the user's current was updated in the foreground, false if the user's current location was updated in the background.
stopped (boolean): true if the user's current location was updated while stopped, false if the user's current location was updated while moving.
deviceType (string): The user's device type, one of iOS, Android, or Web.
createdAt (datetime): The datetime when the user was created.
updatedAt (datetime): The datetime when the user's location was last updated.
geofences (array): An array of the user's current geofences.
trip (dictionary): When a trip has been started, the user's current trip. Present when the trip has a status of started, approaching, or arrived.
place (dictionary): When Places is enabled, the user's current place.
country (dictionary): When Regions is enabled, the user's current country.
state (dictionary): When Regions is enabled, the user's current state. US-only.
dma (dictionary): When Regions is enabled, the user's current DMA (market area). US-only.
postalCode (dictionary): When Regions is enabled, the user's current postal code. US-only.
beacons (array): When beacons have been created, an array of the user's current beacons.
fraud (object): When Fraud is enabled, indicates whether the user passed fraud checks.

Sample object#

{  "_id": "56db1f4613012711002229f4",  "live": true,  "userId": "1",  "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",  "metadata": {    "customId": "123",    "customFlag": false  },  "location": {    "type": "Point",    "coordinates": [-73.97536, 40.78382]  },  "locationAccuracy": 5,  "foreground": true,  "stopped": true,  "deviceType": "iOS",  "updatedAt": "2016-06-10T13:44:10.535Z",  "geofences": [    {      "_id": "56db1f4613012711002229f5",      "tag": "neighborhood",      "externalId": "1",      "description": "Upper West Side",      ...    },    ...  ],  "trip:": {    "_id": "5f3e50491c2b7d005c81f5d9",    "live": true,    "status": "started",    "externalId": "299",    "metadata": {      "Customer Name": "Jacob Pena",      "Car Model": "Green Honda Civic"    },    "mode": "car",    "destinationGeofenceTag": "store",    "destinationGeofenceExternalId": "123",    "destinationLocation": {      "coordinates": [        -105.061198,        39.779366      ],      "type": "Point"    },    "eta": {      "duration": 5.5,      "distance": 1331    },    ...  },  "place": {    "_id": "56db1f4613012711002229f7",    "facebookId": "37965424481",    "name": "Starbucks",    "categories": [      "food-beverage",      "cafe",      "coffee-shop"    ],    "chain": {      "name": "Starbucks",      "slug": "starbucks"    }  },  "country": {    "name": "United States",    "code": "US"  },  "state": {    "name": "New Jersey",    "code": "NJ"  },  "dma": {    "name": "New York",    "code": "501"  },  "postalCode": {    "code": "07302"  },  "beacons": [    {      "type": "ibeacon",      "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d",      "major": "100",      "minor": "1",      "description": "Store #123 - Register #1",      "tag": "store-register",      "externalId": "123-1",      "enabled": true    }  ],  "fraud": {    "verified": true,    "passed": false,    "bypassed": false,    "blocked": false,    "mocked": true,    "jumped": false,    "compromised": false,    "inaccurate": false,    "proxy": false,    "sharing": false    "lastMockedAt": "2023-07-27T17:18:28.536Z",    "lastJumpedAt": "2023-07-27T17:18:28.536Z",    "lastCompromisedAt": null,    "lastInaccurateAt": null,    "lastProxyAt": null,    "lastSharingAt": null  }}

Create a user#

To create a user, call the track endpoint.

On iOS and Android, use the SDK to track users.

List users#

Lists users. Users are sorted descending by updatedAt.

Definition#

GET https://api.radar.io/v1/users

Query parameters#

limit (number, optional): The max number of users to return. A number between 1 and 1000. Defaults to 100.
updatedBefore (datetime, optional): A cursor for use in pagination. Retrieves users updated before the specified datetime. A date or valid ISO date string.
updatedAfter (datetime, optional): A cursor for use in pagination. Retrieves users updated after the specified datetime. A date or valid ISO date string.

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/users" \  -H "Authorization: prj_live_sk_..."

Sample response#

{  "meta": {    "code": 200,    "hasMore": true  },  "users": [    {      "_id": "56db1f4613012711002229f4",      "live": true,      "userId": "1",      "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",      ...    },    ...  ]}

Get a user#

Gets a user. The user can be referenced by Radar _id, userId, or deviceId.

Definition#

GET https://api.radar.io/v1/users/:id

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/users/56db1f4613012711002229f4" \  -H "Authorization: prj_live_sk_..."

Sample response#

{  "meta": {    "code": 200  },  "user": {    "_id": "56db1f4613012711002229f4",    "live": true,    "userId": "1",    "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",    ...  }}

Delete a user#

Deletes a user. The user can be referenced by Radar _id, userId, or deviceId.

Definition#

DELETE https://api.radar.io/v1/users/:id

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/users/56db1f4613012711002229f4" \  -H "Authorization: prj_live_sk_..." \  -X DELETE

Sample response#

{  "meta": {    "code": 200  }}

Trips#

A trip is a sequence of location updates with metadata and a unique ID, optionally with an ETA to a destination geofence. Depending on your use case, a trip may represent a pickup, a delivery, or something else.

Object fields#

_id (string): The unique ID for the trip, provided by Radar. An alphanumeric string.
live (boolean): true if the user was created with your live API key, false if the user was created with your test API key.
externalId (string): A stable unique ID for the trip. Depending on your use case, may represent an order ID, a delivery ID, or something else.
metadata (dictionary): An optional set of custom key-value pairs for the trip, displayed in the trip tracking dashboard.
mode (string): The travel mode for the trip. A string, one of foot, bike, and car.
destinationGeofenceTag (string): For trips with a destination, the tag of the destination geofence.
destinationGeofenceExternalId (string): For trips with a destination, the external ID of the destination geofence.
destinationLocation (point): For trips with a destination, the location of the destination geofence.
eta (dictionary): For trips with a destination, the ETA to the destination geofence based on the travel mode for the trip, including duration in minutes and distance in meters.
approachingThreshold (number): For trips with a destination, the trip approaching threshold setting for the trip (in minutes). Overrides the geofence-level and project-level trip approaching threshold settings.
createdAt (datetime): The datetime when the trip was started.
updatedAt (datetime): The datetime when the trip's location was last updated.
scheduledArrivalAt (datetime): Required for the Olo order firing integration, the backstop datetime when the device on the trip is expected to arrive. The order will be fired approachingThreshold minutes before scheduledArrivalAt.
orderFiredAt (datetime): From the Olo integration, the datetime when the order associated with the trip was fired.
arrivedAt (datetime): For trips with a destination, the datetime when the user arrived at the trip destination (entered the destination geofence).
completedAt (datetime): The datetime when the trip was stopped.
status (string): The status of the trip, one of pending, started, approaching, arrived, expired, completed, or canceled.
user (dictionary): The user for which the trip is being tracked.
userId (string): The external ID of the user for which the trip is being tracked.
locations (array): The location updates tracked while the trip was active. An array of Points in GeoJSON format.
delay (dictionary): The predicted delay for the trip, including a delayed boolean flag and a scheduledArrivalTimeDelay with the delay amount in minutes.

Sample object#

{  "_id": "5f3e50491c2b7d005c81f5d9",  "live": true,  "status": "started",  "externalId": "299",  "metadata": {    "Customer Name": "Jacob Pena",    "Car Model": "Green Honda Civic"  },  "mode": "car",  "destinationGeofenceTag": "store",  "destinationGeofenceExternalId": "123",  "destinationLocation": {    "coordinates": [      -105.061198,      39.779366    ],    "type": "Point"  },  "approachingThreshold": 3,  "eta": {    "duration": 5.5,    "distance": 1331  },  "createdAt": "2020-08-20T10:27:55.830Z",  "updatedAt": "2020-08-20T10:30:55.837Z",  "user": {    "_id": "56db1f4613012711002229f4",    "userId": "1",    "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8"  },  "userId": "1",  "locations": [    {      "type": "Point",      "coordinates": [        -105.062645,        39.766059819860864      ],      "updatedAt": "2020-08-20T10:29:55.897Z"    },    {      "type": "Point",      "coordinates": [        -105.06267319809022,        39.769057068070715      ],      "updatedAt": "2020-08-20T10:30:55.837Z"    }  ],  "delay": {    "delayed": false,    "scheduledArrivalTimeDelay": 0  }}

Get a trip#

Gets a trip. The trip can be referenced by Radar _id or externalId.

Definition#

GET https://api.radar.io/v1/trips/:id
GET https://api.radar.io/v1/trips/:externalId

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/trips/299" \  -H "Authorization: prj_live_sk_..."

Authentication level#

Secret

Sample response#

{  "_id": "5f3e50491c2b7d005c81f5d9",  "live": true,  "status": "started",  "externalId": "299",  "metadata": {    "Customer Name": "Jacob Pena",    "Car Model": "Green Honda Civic"  },  "mode": "car",  "destinationGeofenceTag": "store",  "destinationGeofenceExternalId": "123",  "destinationLocation": {    "coordinates": [      -105.061198,      39.779366    ],    "type": "Point"  },  "eta": {    "duration": 5.5,    "distance": 1331  },  ...}

List trips#

Definition#

Lists trips. Trips are sorted descending by eta.

GET https://api.radar.io/v1/trips

Query parameters#

status (string, optional): Retrieves trips by status. A string, comma-separated including one or more of pending, started, approaching, arrived, completed, canceled, expired.
destinationGeofenceTag (string, optional): Retrieves trips with the destination geofence tag.
destinationGeofenceExternalId (string, optional): Retrieves trips with the destination geofence external ID.
externalId (string, optional): A stable unique ID for the trip.
userId (string, optional): The external ID of the user for which the trip is being tracked.
includeLocations (boolean, optional): Whether to include locations on trips. Defaults to false.
createdAfter (datetime, optional): A cursor for use in pagination. Retrieves trips created after the specified datetime. A date or valid ISO date string.
createdBefore (datetime, optional): A cursor for use in pagination. Retrieves trips created before the specified datetime. A date or valid ISO date string.
limit (number, optional): The max number of addresses to return. A number between 1 and 1000. Defaults to 500.

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/trips?status=started&destinationGeofenceTag=store&destinationGeofenceExternalId=123" \  -H "Authorization: prj_live_sk_..."

Authentication level#

Secret

Sample response#

{  "meta": {    "code": 200  },  "trips": [    {      "_id": "5f3e50491c2b7d005c81f5d9",      "live": true,      "status": "started",      "externalId": "299",      "metadata": {        "Customer Name": "Jacob Pena",        "Car Model": "Green Honda Civic"      },      "mode": "car",      "destinationGeofenceTag": "store",      "destinationGeofenceExternalId": "123",      "destinationLocation": {        "coordinates": [          -105.06119826017914,          39.7793665        ],        "type": "Point"      },      "eta": {        "duration": 5.5,        "distance": 1331      },      "createdAt": "2020-08-20T10:27:55.830Z",      "updatedAt": "2020-08-20T10:30:55.837Z",      ...    },    ...  ]}

Create a new trip#

Use the SDK to start trips and track users for most use cases.

Trips can also be created server-side or through integrations (e.g., Olo). Location updates with the specified userId from the SDK will update the trip for that user.

Definition#

Creates a new trip.

POST https://api.radar.io/v1/trips

Body parameters#

externalId (string, required): A stable unique ID for the trip. Depending on your use case, it may represent an order ID, a delivery ID, or something else.
destinationGeofenceTag (string, optional): For trips with a destination, the tag of the destination geofence.
destinationGeofenceExternalId (string, optional): For trips with a destination, the external ID of the destination geofence.
userId (string, optional): The external ID of the user for which the trip is being tracked.
mode (string, optional): The travel mode for the trip. A string, one of foot, bike, and car. Defaults to car.
approachingThreshold (number, optional): For trips with a destination, the trip approaching threshold setting for the trip (in minutes). Overrides the geofence-level and project-level trip approaching threshold settings.
scheduledArrivalAt (datetime): Required for the Olo order firing integration, the backstop datetime when the device on the trip is expected to arrive. The order will be fired approachingThreshold minutes before scheduledArrivalAt.

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/trips" \  -H "Authorization: prj_test_pk_..." \  -X POST \  -d "externalId=123" \  -d "mode=car" \  -d "destinationGeofenceTag=store" \  -d "destinationGeofenceExternalId=1" \  -d "userId=001" \  -d "approachingThreshold=3" \  -d "metadata={\"foo\": \"bar\"}"

Authentication level#

Publishable

Sample response#

{  "meta": {    "code": 200,  },  "trip": {    "_id": "6334960ad9735600116b7ab5",    "live": false,    "externalId": "123",    "userId": "001",    "mode": "car",    "status": "pending",    "destinationGeofenceTag": "store",    "destinationGeofenceExternalId": "1",    "destinationLocation": {      "type": "Point",      "coordinates": [        -73.977797,        40.783826      ]    },    "metadata": {      "foo": "bar"    },    "approachingThreshold": 3,    "user": {      "_id": "56db1f4613012711002229f4",      "userId": "001",      "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8"    },    "locations": [],  }}

Update a trip#

Updates a trip. The trip can be referenced by Radar _id or externalId.

On iOS and Android, use the SDK to update trips.

Definition#

PATCH https://api.radar.io/v1/trips/:id/update
PATCH https://api.radar.io/v1/trips/:externalId/update

Body parameters#

status (string, required): The new status of the trip, one of pending,started, approaching, arrived, completed, or canceled.
mode (string, optional): The travel mode for the trip. A string, one of foot, bike, and car.
destinationGeofenceTag (string, optional): For trips with a destination, the tag of the destination geofence.
destinationGeofenceExternalId (string, optional): For trips with a destination, the external ID of the destination geofence.
approachingThreshold (number, optional): For trips with a destination, the trip approaching threshold setting for the trip (in minutes). Overrides the geofence-level and project-level trip approaching threshold settings.
scheduledArrivalAt (datetime, optional): Required for the Olo order firing integration, the backstop datetime when the device on the trip is expected to arrive. The order will be fired approachingThreshold minutes before scheduledArrivalAt.
metadata (dictionary, optional): An optional set of custom key-value pairs for the trip.

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/trips/299/update" \  -H "Authorization: prj_live_sk_..."  -X PATCH  -d "status=completed"

Authentication level#

Publishable

Sample response#

{  "meta": {    "code": 200    },   "trip": {    "_id": "6334960ad9735600116b7ab5",    "live": false,    "externalId": "123",    "userId": "001",    "mode": "car",    "status": "completed",    "destinationGeofenceTag": "store",    "destinationGeofenceExternalId": "1",    "destinationLocation": {      "type": "Point",      "coordinates": [        -73.977797,        40.783826      ]    },    "metadata": {      "foo": "bar"    },    "approachingThreshold": 3,    "user": {      "_id": "56db1f4613012711002229f4",      "userId": "001",      "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8"    },    "locations": [],  }}

Delete a trip#

Deletes a trip. The trip can be referenced by Radar _id or externalId.

Definition#

DELETE https://api.radar.io/v1/trips/:id

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/trips/56db1f4613012711002229f4" \  -H "Authorization: prj_live_sk_..." \  -X DELETE

Sample response#

{  "meta": {    "code": 200  }}

Geofences#

A geofence represents a custom region or place monitored in your project. Geofences can be uniquely referenced by Radar _id or by tag and externalId.

Object fields#

_id (string): The unique ID for the geofence, provided by Radar. An alphanumeric string.
createdAt (datetime): The datetime when the geofence was created.
updatedAt (datetime): The datetime when the geofence was last updated.
live (boolean): true if the geofence was created with your live API key, false if the user was created with your test API key.
tag (string): A group for the geofence.
externalId (string): An external ID for the geofence that maps to your internal database.
description (string): A description for the geofence.
type (string): The type of geofence geometry, one of circle, polygon, or isochrone.
geometry (polygon): The geometry of the geofence. Coordinates for type polygon. A calculated polygon approximation for type circle and isochrone. A Polygon in GeoJSON format.
geometryCenter (point): The center for type circle. The calculated centroid of the polygon for type polygon. The destination for type isochrone. A Point in GeoJSON format.
geometryRadius (number): The radius in meters for type circle. The calculated approximate radius of the polygon for type polygon. The travel duration in minutes for type isochrone.
mode (string): The travel mode for type isochrone.
metadata (dictionary): An optional set of custom key-value pairs for the geofence.
userId (string): An optional user restriction for the geofence. If set, the geofence will only generate events for the specified user. If not set, the geofence will generate events for all users.
ip (string, optional): An optional IP address restriction for the geofence. A string of comma-separated IP address ranges, each of which could be a single IP (8.8.8.8), wildcard notation (8.8.8.*), or CIDR notation (8.8.8.8/24). If set, the geofence will only generate events for requests from the specified IP address. If not set, the geofence will generate events for all requests.
tripApproachingThreshold (number): The trip approaching threshold setting for the geofence (in minutes). Overrides the project-level trip approaching threshold setting.
dwellThreshold (number): An optional field to trigger dwell events. If set and user.dwelled_in_geofence is enabled in settings, an event is triggered when a user dwells in the geofence longer than the threshold (in minutes).
enabled (boolean): If true, the geofence will generate events. If false, the geofence will not generate events. Defaults to true.
operatingHours (dictionary): An optional set of key-value pairs restricting the operating hours of the geofence. Each key is a day of the week, and each value is a list of pairs, where a pair indicates one opening and closing time for that day in HH:mm format.

Sample object#

{  "_id": "56db1f4613012711002229f5",  "createdAt": "2016-06-10T13:44:10.535Z",  "updatedAt": "2016-06-10T14:40:10.535Z",  "live": true,  "tag": "venue",  "externalId": "2",  "description": "Coffee Shop",  "type": "circle",  "geometry": {    "type": "Polygon",    "coordinates": [[...]]  },  "geometryCenter": {    "type": "Point",    "coordinates": [-73.97536, 40.78382]  },  "geometryRadius": 50,  "metadata": {    ...  },  "enabled": true}

List geofences#

Definition#

Lists geofences. Geofences are sorted descending by updatedAt.

GET https://api.radar.io/v1/geofences

Query parameters#

limit (number, optional): The max number of geofences to return. A number between 1 and 1000. Defaults to 100.
createdBefore (datetime, optional): Retrieves geofences created before the specified datetime. A date or valid ISO date string.
createdAfter (datetime, optional): Retrieves geofences created after the specified datetime. A date or valid ISO date string.
updatedBefore (datetime, optional): A cursor for use in pagination. Retrieves geofences updated before the specified datetime. A date or valid ISO date string.
updatedAfter (datetime, optional): A cursor for use in pagination. Retrieves geofences updated after the specified datetime. A date or valid ISO date string.
tag (string, optional): Retrieves geofences with the specified tag.
externalId (string, optional): Retrieves geofences with the specified externalId.

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/geofences" \  -H "Authorization: prj_live_sk_..."

Authentication level#

Secret

Sample response#

{  "meta": {    "code": 200,    "hasMore": true  },  "geofences": [    {      "_id": "56db1f4613012711002229f5",      "createdAt": "2016-06-10T13:44:10.535Z",      "live": true,      "tag": "venue",      "externalId": "2",      "description": "Coffee Shop",      "type": "circle",      ...    },    ...  ]}

Get a geofence#

Gets a geofence. The geofence can be uniquely referenced by Radar _id or by tag and externalId.

Definition#

GET https://api.radar.io/v1/geofences/:id
GET https://api.radar.io/v1/geofences/:tag/:externalId

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/geofences/56db1f4613012711002229f5" \  -H "Authorization: prj_live_sk_..."

Sample response#

{  "meta": {    "code": 200  },  "geofence": {    "_id": "56db1f4613012711002229f5",    "createdAt": "2016-06-10T13:44:10.535Z",    "live": true,    "tag": "venue",    "externalId": "2",    "description": "Coffee Shop",    "type": "circle",    ...  }}

Upsert a geofence#

Upserts a geofence. The geofence can be uniquely referenced by tag and externalId or by the Radar _id. If a geofence with the specified tag and externalId already exists, it will be updated. If not, it will be created.

Definition#

PUT https://api.radar.io/v1/geofences/:tag/:externalId
PUT https://api.radar.io/v1/geofences/:id

Body parameters#

description (string, required): A description for the geofence.
type (string, required): The type of geofence geometry. A string, one of circle, polygon, or isochrone.
coordinates (array, required if address and placeId are not included): An array or JSON string representing a center for type circle or a destination for type isochrone in the format [longitude,latitude]. A two-dimensional array or JSON string representing a closed ring of between 4 and 2,000 coordinates in the format [[longitude0, latitude0],[longitude1,latitude1],[longitude2,latitude2],...,[longitude0,latitude0]] for type polygon. Note that longitude comes before latitude, a GeoJSON convention.
address (string, required if coordinates and placeId are not included): An address to search for, and if found, will represent the center for type circle or isochrone. If address and coordinates are both provided, they must be nearby, and coordinates will take precedent. Ignored for type polygon.
radius (number, required for type circle and isochrone): The radius in meters for type circle, a number between 10 and 10000. The travel duration in minutes for type isochrone. Ignored for type polygon.
metadata (dictionary, optional): An optional set of custom key-value pairs for the geofence. A dictionary or JSON string with up to 16 keys and values of type string, boolean, or number.
userId (string, optional): An optional user restriction for the geofence. If set, the geofence will only generate events for the specified user. If not set, the geofence will generate events for all users.
ip (string, optional): An optional IP address restriction for the geofence. A string of comma-separated IP address ranges, each of which could be a single IP (8.8.8.8), wildcard notation (8.8.8.*), or CIDR notation (8.8.8.8/24). If set, the geofence will only generate events for requests from the specified IP address. If not set, the geofence will generate events for all requests.
enabled (boolean, optional): If true, the geofence will generate events. If false, the geofence will not generate events. Defaults to true.
disableAfter (datetime, optional): Use to create temporary geofences. If set, the geofence will be disabled after the specified datetime. A date or valid ISO date string.
deleteAfter (datetime, optional): Use to create temporary geofences. If set, the geofence will be deleted after the specified datetime. A date or valid ISO date string.
stopDetection (boolean, optional): The stop detection setting for the geofence. Overrides the project-level stop detection setting.
mode (string, required for type isochrone): The travel mode for type isochrone.
tripApproachingThreshold (number, optional): The trip approaching threshold setting for the geofence (in minutes). Overrides the project-level trip approaching threshold setting.
dwellThreshold (number, optional): An optional field to trigger dwell events. If set and user.dwelled_in_geofence is enabled in settings, an event is triggered when a user dwells in the geofence longer than the threshold (in minutes).
placeId (string, required if coordinates and address are not included): For place matching, an optional id of the Radar place to match to the geofence. If provided and found, the place centroid will override coordinates and address.
operatingHours (dictionary, optional): An optional set of key-value pairs restricting the operating hours of the geofence. Each key is a day of the week (e.g., Sunday) or the three letter abbreviation of the day (e.g., Sun), case insensitive. Each value is a list of pairs, where a pair indicates one opening and closing time for that day. For example, a restaurant only open for lunch and dinner on Sundays would be { Sunday: [["11:00", "14:00"], ["19:00", "22:00"]] }. Accepted time formats include h:mm aa (e.g., 12:45 AM) and HH:mm (e.g., 00:45). If not set, the geofence will always be open.

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/geofences/venue/2" \  -H "Authorization: prj_live_sk_..." \  -X PUT \  -d "description=Coffee Shop" \  -d "type=circle" \  -d "coordinates=[-73.97536,40.78382]" \  -d "radius=50"

Sample response#

{  "meta": {    "code": 200  },  "geofence": {    "_id": "56db1f4613012711002229f5",    "createdAt": "2016-06-10T13:44:10.535Z",    "live": true,    "tag": "venue",    "externalId": "2",    "description": "Coffee Shop",    "type": "circle",    ...  }}

Delete a geofence#

Deletes a geofence. The geofence can be uniquely referenced by Radar _id or by tag and externalId.

Definition#

DELETE https://api.radar.io/v1/geofences/:id
DELETE https://api.radar.io/v1/geofences/:tag/:externalId

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/geofences/56db1f4613012711002229f5" \  -H "Authorization: prj_live_sk_..." \  -X DELETE

Sample response#

{  "meta": {    "code": 200  }}

Get users in a geofence#

Gets users currently in a geofence.

Definition#

GET https://api.radar.io/v1/geofences/:tag/:externalId/users

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/geofences/venue/2/users" \  -H "Authorization: prj_live_sk_..."

Sample response#

{  "meta": {    "code": 200,    "hasMore": false  },  "users": [    {      "_id": "611ace2eb08f300047c904e9",      "location": {        "type": "Point",        "coordinates": [          73.97536,          40.78382        ]      },      ...    }    ...  ]}

Events#

An event represents a change in user state. Events can be uniquely referenced by Radar _id.

Object fields#

_id (string): The unique ID for the event, provided by Radar. An alphanumeric string.
createdAt (datetime): The datetime when the event was created on the mobile client.
actualCreatedAt (datetime): The datetime when the event was created on the server. Mobile operating systems can deliver location updates on a delay, resulting in a delta between this field and createdAt.
live (boolean): true if the event was generated for a user and geofence created with your live API key, false if the event was generated for a user and geofence created with your test API key.
type (string): The type of event. By default, events are generated when a user enters a geofence (type user.entered_geofence) or exits a geofence (type user.exited_geofence). Places and Regions also generate events.
user (dictionary): The user for which the event was generated.
geofence (dictionary): For user.entered_geofence and user.exited_geofence events, the geofence for which the event was generated, including description, tag, and externalId.
place (dictionary): For user.entered_place and user.exited_place events, the place for which the event was generated, including name, categories, chain, and facebookId.
alternatePlaces (array): For user.entered_place events, alternate place candidates.
verifiedPlace (dictionary): For verified user.entered_place events, the verified place.
location (point): The location of the user at the time of the event, a Point in GeoJSON format.
locationAccuracy (number): The accuracy of the user's location at the time of the event in meters.
confidence (number): The confidence level of the event, one of 3 (high), 2 (medium), or 1 (low).
duration (number): On exit events, the duration between entry and exit events, in minutes.

Sample object#

{  "_id": "56db1f4613012711002229f6",  "createdAt": "2016-06-10T13:44:10.535Z",  "live": true,  "type": "user.exited_geofence",  "location": {    "type": "Point",    "coordinates": [-73.97779, 40.78382]  },  "locationAccuracy": 5,  "confidence": 3,  "duration": 48.38920,  "user": {    "_id": "56db1f4613012711002229f4",    "userId": "1",    "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",    ...  },  "geofence": {    "_id": "56db1f4613012711002229f5",    "tag": "venue",    "externalId": "2",    "description": "Coffee Shop",    ...  }}

Generate an entry or exit event#

To generate an entry or exit event, call the track endpoint to trigger an event. For example, specify a latitude and longitude to enter a geofence that you have created.

On iOS and Android, use the SDK to track users.

Log a conversion#

Conversions are available on the Enterprise plan.

Logs a conversion to analyze alongside other location activity in your app. This can represent anything from a purchase or signup to engagement with an in-app feature.

Definition#

POST https://api.radar.io/v1/events

Body parameters#

name (string, required): The name of the conversion. Should be generic (e.g., in_app_purchase). Only alphanumeric characters and underscores are supported.
metadata (dictionary, optional): The metadata of the conversion. This data cannot contain any sensitive or personally identifiable information.
revenue (number, optional): The revenue of the conversion. Used to associate an amount with a transactional conversion such as a purchase or coupon redemption.
userId (string, optional): The stable unique ID for the user. Used to identify logged in users.
deviceId (string, optional): A device ID for the user. Used to identify logged out users.
installId (string, optional): An install ID for the user. Used to identify users who have opted out of location permissions. Can be a random alphanumeric string for users that don't exist in Radar.
createdAt (string, optional): The datetime when the conversion occurred.
duration (number, optional): The duration of the conversion in minutes.

Authentication level#

Publishable

Default rate limit#

10 requests per second

Sample request#

curl "https://api.radar.io/v1/events" \  -H "Authorization: prj_live_pk_..." \  -X POST \  -d "name=conversion" \  -d "userId=user123"

Sample response#

{  "meta": {    "code": 200  },  "event": {    "_id": "56db1f4613012711002229f6",    "createdAt": "2016-06-10T13:44:10.535Z",    "live": true,    "type": "conversion",    "confidence": 3,    "user": {      "_id": "56db1f4613012711002229f4",      "userId": "user123",      "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",      ...    }  }}

Beacons#

A beacon represents a Bluetooth beacon monitored in your project. Beacons can be uniquely referenced by Radar _id or by tag and externalId.

Object fields#

_id (string): A unique ID for the beacon, provided by Radar. An alphanumeric string.
createdAt (datetime): The datetime when the beacon was created.
updatedAt (datetime): The datetime when the beacon was last updated.
live (boolean): true if the beacon was created with your live API key, false if the beacon was created with your test API key.
description (string): A display name for the beacon.
tag (string): A group for the beacon.
externalId (string): An external ID for the beacon.
type (string, required): The type of beacon, one of ibeacon (supported on iOS and Android) or eddystone (supported on Android only).
uuid (string, required for ibeacon): For iBeacons, the UUID of the beacon.
major (string, required for ibeacon): For iBeacons, the major ID of the beacon.
minor (string, required for ibeacon): For iBeacons, the minor ID of the beacon.
uid (string, required for eddystone): For Eddystone beacons, the UID of the beacon.
instance (string, required for eddystone): For Eddystone beacons, the instance ID of the beacon.
geometry (point): The approximate location of the beacon, used to sync nearby beacons (within 1 kilometer) to the SDK. Coordinates for type point in [longitude,latitude] format.
enabled (boolean): If true, the beacon will generate events. If false, the beacon will not generate events.
metadata (dictionary): A set of custom key-value pairs for the beacon. A JSON string representing a dictionary with up to 16 keys and values of type string, boolean, or number.

Sample object#

{  "_id": "60f6da60cf4cc0a72a6c070b",  "createdAt": "2021-07-20T14:27:22.283Z",  "updatedAt": "2021-07-20T14:27:22.283Z",  "live": false,  "description": "Store #123 - Register #1",  "tag": "store-register",  "externalId": "123-1",  "type": "ibeacon",  "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d",  "major": "100",  "minor": "1",  "geometry": {    "type": "Point",    "coordinates": [      -73.975384,      40.783747    ]  },  "enabled": true,  "metadata": {    "supportsContactlessPayments": true  }}

List beacons#

Lists beacons. Beacons are sorted descending by createdAt.

Definition#

GET https://api.radar.io/v1/beacons

Query parameters#

limit (number, optional): The max number of beacons to return. A number between 1 and 1000. Defaults to 100.
createdBefore (datetime, optional): A cursor for use in pagination. Retrieves beacons updated before the specified datetime. A date or valid ISO date string.
createdAfter (datetime, optional): A cursor for use in pagination. Retrieves beacons updated after the specified datetime. A date or valid ISO date string.
tag (string, optional): Retrieves beacons with the specified tag.
externalId (string, optional): Retrieves beacons with the specified externalId.

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/beacons" \  -H "Authorization: prj_live_sk_..."

Sample response#

{  "meta": {    "code": 200,    "hasMore": true  },  "beacons": [    {      "_id": "6109a4b16dbfe3de2cb03924",      "createdAt": "2021-08-03T20:18:57.888Z",      "updatedAt": "2021-08-03T20:18:57.888Z",      "live": true,      "description": "Store #123 - Register #1",      ...    },    ...  ]}

Get a beacon#

Gets a beacon. The beacon can be uniquely referenced by Radar _id or by tag and externalId.

Definition#

GET https://api.radar.io/v1/beacons/:id
GET https://api.radar.io/v1/beacons/:tag/:externalId

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/beacons/6109a4b16dbfe3de2cb03924" \  -H "Authorization: prj_live_sk_..."

Sample response#

{  "meta": {    "code": 200  },  "beacon": {    "_id": "6109a4b16dbfe3de2cb03924",    "createdAt": "2021-08-03T20:18:57.888Z",    "updatedAt": "2021-08-03T20:18:57.888Z",    "live": true,    "description": "Store #123 - Register #1",    "tag": "store-register",    "externalId": "123-1",    ...  }}

Create a beacon#

Creates a beacon.

Definition#

POST https://api.radar.io/v1/beacons

Body parameters#

description (string, required): A display name for the beacon.
tag (string, required): A group for the beacon.
externalId (string, required): An external ID for the beacon.
type (string, required): The type of beacon, one of ibeacon (supported on iOS and Android) or eddystone (supported on Android only).
uuid (string, required for ibeacon): For iBeacons, the UUID of the beacon.
major (string, required for ibeacon): For iBeacons, the major ID of the beacon.
minor (string, required for ibeacon): For iBeacons, the minor ID of the beacon.
uid (string, required for eddystone): For Eddystone beacons, the UID of the beacon.
instance (string, required for eddystone): For Eddystone beacons, the instance ID of the beacon.
coordinates (point, required): The approximate location of the beacon, used to sync nearby beacons (within 1 kilometer) to the SDK. Coordinates in [longitude,latitude] format.
enabled (boolean, optional): If true, the beacon will generate events. If false, the beacon will not generate events.
metadata (dictionary, optional): A set of custom key-value pairs for the beacon. A JSON string representing a dictionary with up to 16 keys and values of type string, boolean, or number.

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/beacons" \  -H "Authorization: prj_live_sk_..." \  -X POST \  -d "description=Store #123 - Register #1" \  -d "tag=store-register" \  -d "tag=123-1" \  -d "type=ibeacon" \  -d "uuid=b9407f30-f5f8-466e-aff9-25556b57fe6d" \  -d "major=100" \  -d "minor=1"  -d "coordinates=[-105.94653744704361,35.70654086799666]" \  -d "enabled=true"

Sample response#

{  "meta": {    "code": 200  },  "beacon": {    "_id": "6116d947049aee0089a682a2",    "createdAt": "2021-08-13T20:42:47.711Z",    "updatedAt": "2021-08-13T20:42:47.711Z",    "live": true,    "description": "Store #123 - Register #1",    "tag": "store-register",    "externalId": "123-1",    ...  }}

Upsert a beacon#

Upserts a beacon. The beacon can be uniquely referenced by Radar _id or by tag and externalId. If a beacon with the specified tag and externalId already exists, it will be updated. If not, it will be created.

Definition#

PUT https://api.radar.io/v1/beacons/:id
PUT https://api.radar.io/v1/beacons/:tag/:externalId

Body parameters#

description (string, required): A display name for the beacon.
type (string, required): The type of beacon, one of ibeacon (supported on iOS and Android) or eddystone (supported on Android only).
uuid (string, required for ibeacon): For iBeacons, the UUID of the beacon.
major (string, required for ibeacon): For iBeacons, the major ID of the beacon.
minor (string, required for ibeacon): For iBeacons, the minor ID of the beacon.
uid (string, required for eddystone): For Eddystone beacons, the UID of the beacon.
instance (string, required for eddystone): For Eddystone beacons, the instance ID of the beacon.
coordinates (point, required): The approximate location of the beacon, used to sync nearby beacons (within 1 kilometer) to the SDK. Coordinates in [longitude,latitude] format.
metadata (dictionary, optional): An optional set of custom key-value pairs for the beacon. A JSON string representing a dictionary with up to 16 keys and values of type string, boolean, or number.
enabled (boolean, optional): If true, the beacon will generate events. If false, the beacon will not generate events. Defaults to true.

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/beacons/store-register/123-1" \  -H "Authorization: prj_live_sk_..." \  -X PUT \  -d "description=Store #123 - Register #1" \  -d "tag=store-register" \  -d "externalId=123-1" \  -d "type=ibeacon" \  -d "uuid=b9407f30-f5f8-466e-aff9-25556b57fe6d" \  -d "major=100" \  -d "minor=1" \  -d "coordinates=[-105.94653744704361,35.70654086799666]" \  -d "enabled=true"

Sample response#

{  "meta": {    "code": 200  },  "beacon": {    "_id": "6116d947049aee0089a682a2",    "createdAt": "2021-08-13T20:42:47.711Z",    "updatedAt": "2021-08-13T20:42:47.711Z",    "live": true,    "description": "Store #123 - Register #1",    "tag": "store-register",    "externalId": "123-1",    ...  }}

Delete a beacon#

Deletes a beacon. The beacon can be uniquely referenced by Radar _id or by tag and externalId.

Definition#

DELETE https://api.radar.io/v1/beacons/:id
DELETE https://api.radar.io/v1/beacons/:tag/:externalId

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/beacons/56db1f4613012711002229f4" \  -H "Authorization: prj_live_sk_..." \  -X DELETE

Sample response#

{  "meta": {    "code": 200  }}

Manage your Radar project settings#

Places settings#

Places settings represents your current project settings for Places.

Object fields#

chainMetadata (dictionary): Current metadata associated with each Radar chain.
chainMappings (dictionary): Current mapping associated with each Radar chain.
placeFilters (dictionary): Current chains and category filtering for place entry and exit event generation.

Get Places settings#

Gets your current Places settings.

Definition#

GET https://api.radar.io/v1/settings

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/settings" \  -H "Authorization: prj_live_sk_..." \  -X GET

Sample response#

{  "meta": {    "code": 200  },  "chainMetadata": {    "mcdonalds": {      "availableDeals": true,    },    "starbucks": {      "availableDeals": true,    }  },  "chainMappings": {    "mcdonalds": "retailer1",    "starbucks": "retailer2"  },  "placeFilters": {    "chain": [      "mcdonalds",      "starbucks"    ],    "category": [      "restaurant"    ]  }}

Update Places settings#

Updates your Places settings.

Definition#

PATCH https://api.radar.io/v1/settings

Default rate limit#

10 requests per second

Authentication level#

Secret

Sample request#

curl "https://api.radar.io/v1/settings" \  -H "Authorization: prj_live_sk_..." \  -H "Content-Type: application/json" \  -X PATCH \  -d '{"chainMetadata":{"mcdonalds":{"availableDeals":false}},"chainMappings":{"mcdonalds":"retailer1"},"placeFilters":{"chain":["mcdonalds"]}}'

Sample response#

{  "meta": {    "code": 200  },  "chainMetadata": {    "mcdonalds": {      "availableDeals": false    }  },  "chainMappings": {    "mcdonalds": "retailer1"  },  "placeFilters": {    "chain": [      "mcdonalds"    ]  }}