> ## Documentation Index
> Fetch the complete documentation index at: https://radarlabs-jasonliu-test.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# API Reference
Use Radar APIs as [building blocks for location-based products and services](#building-blocks) 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](#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](https://dashboard.radar.com/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](/sdk#authentication)). 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**
```sh theme={null}
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**
```sh theme={null}
{
"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](/sdk/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](/faqs#what-are-privacy-best-practices-for-radar) for more information.
This endpoint is stateful. For anonymous or stateless context, call the [context](#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](/geofences#confidence-and-accuracy) 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
**Sample request**
```sh theme={null}
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**
```json theme={null}
{
"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](#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**
```bash theme={null}
curl "https://api.radar.io/v1/context?coordinates=40.78382,-73.97536" \
-H "Authorization: prj_live_pk_..."
```
**Sample response**
```sh theme={null}
{
"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](#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`, `postalCode`, `locality`, `county`, `state`, `country`, `coarse`, and `fine`. Note that `coarse` includes all of `postalCode`, `locality`, `county`, `state`, and `country`, whereas `fine` includes `address` and `place`. 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](/regions/countries).
* **`lang`** (string, optional): Specifies the language for the results. A string, one of `ar`, `de`, `en`, `es`, `fr`, `ja`, `ko`, `pt`, `ru`, `zh`. Defaults to `en`.
**Authentication level**
Publishable
**Default rate limit**
10 requests per second (contact your customer success manager to increase rate limit)
**Sample request**
```
curl "https://api.radar.io/v1/geocode/forward?query=20+jay+st+brooklyn+ny" \
-H "Authorization: prj_live_pk_..."
```
**Sample response**
```json theme={null}
{
"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",
"timeZone": {
"id": "America/New_York",
"name": "Eastern Daylight Time",
"code": "EDT",
"currentTime": "2024-04-09T10:12:00-04:00",
"utcOffset": -14400,
"dstOffset": 3600
}
}
]
}
```
#### **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`, `postalCode`, `locality`, `county`, `state`, `country`, `coarse`, and `fine`. Note that `coarse` includes all of `postalCode`, `locality`, `county`, `state`, and `country`, whereas `fine` includes `address` and `place`. If not provided, results from `address` and `coarse` layers will be returned.
**Authentication level**
Publishable
**Default rate limit**
10 requests per second (contact your customer success manager to increase rate limit)
**Sample request**
```
curl "https://api.radar.io/v1/geocode/reverse?coordinates=40.70390,-73.98670" \
-H "Authorization: prj_live_pk_..."
```
**Sample responses**
```json theme={null}
{
"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",
"timeZone": {
"id": "America/New_York",
"name": "Eastern Daylight Time",
"code": "EDT",
"currentTime": "2024-04-09T10:12:00-04:00",
"utcOffset": -14400,
"dstOffset": 3600
},
"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 per device
**Sample request**
```
curl "https://api.radar.io/v1/geocode/ip" \
-H "Authorization: prj_live_pk_..."
```
**Sample response**
```json theme={null}
{
"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",
"timeZone": {
"id": "America/New_York",
"name": "Eastern Daylight Time",
"code": "EDT",
"currentTime": "2024-04-09T10:12:00-04:00",
"utcOffset": -14400,
"dstOffset": 3600
},
},
"proxy": false,
"ip": "107.77.199.117"
}
```
### **Search**
#### **Autocomplete**
Autocompletes partial addresses and place names, sorted by relevance and proximity.
**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 prefer search results near. A string in the format `latitude,longitude`. If not provided, the request IP geolocation will be used to anchor the search.
* `layers` (string, optional): Optional layer filters. A string, comma-separated, including one or more of `place`, `address`, `postalCode`, `locality`, `county`, `state`, `country`, `coarse`, and `fine`. Note that `coarse` includes all of `postalCode`, `locality`, `county`, `state`, and `country`, whereas `fine` includes `address` and `place`. 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.
* `countryCode` (string, optional): An optional countries filter. A string of comma-separated countries, the unique 2-letter [country code](/regions/countries).
* `lang` (string, optional): Specifies the language for the results. A string, one of `ar`, `de`, `en`, `es`, `fr`, `ja`, `ko`, `pt`, `ru`, `zh`. Defaults to `en`.
**Query best practices**
**US/CA:** For customers using autocomplete for full address completion (i.e. checkout page), pass in `layers`: `address`, `countryCode`: `US, CA`.
**International:** For customers implementing autocomplete for international address completion use cases, contact your solutions engineer for best practices based on your use case.
**Authentication level**
Publishable
**Default rate limit**
10 requests per second (contact your customer success manager to increase rate limit)
**Sample request**
```
curl "https://api.radar.io/v1/search/autocomplete?query=brooklyn+roasting&layers=place&near=40.70390,-73.98670" \
-H "Authorization: prj_live_pk_..."
```
**Sample response**
```json theme={null}
{
"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](https://docs.radar.com/api#distance). 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**
100 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**
```json theme={null}
{
"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**
* `near` (string, required): A location for the search. A string in the format `latitude,longitude`.
* `limit` (number, optional): The max number of geofences to return. A number between 1 and 1000. Defaults to 100.
* `radius` (number, optional): Optional radius to search, in meters.
* `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`.
* `includeGeometry` (boolean, optional): Include geofence geometries in the response. Defaults to `true`.
**Note:** To retrieve more than 100 results, `includeGeometries` must be set to `false`.
**Authentication level**
Publishable
**Default rate limit**
100 requests per second
**Sample request**
```
curl "https://api.radar.io/v1/search/geofences?tags=store&metadata%5Boffers%5D=true&near=40.783826,-73.975363&radius=1000&limit=10" \
-H "Authorization: prj_live_pk_..."
```
**Sample response**
```json theme={null}
{
"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](/places#chains) filters. A string, comma-separated. If your project has a [chain mapping](/places#mappings), the mapped ID can be used in place of the chain slug. If not provided, `categories` must be provided.
* `categories` (string, optional): [Category](/places#categories) 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](/places#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 1 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**
150 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**
```json theme={null}
{
"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 for enterprise customers.
This endpoint is best for validating complete structured addresses. For partial addresses or place names, call the [autocomplete](/api#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
On US addresses, an `analysis` field may be returned, which contains the following fields:
* `unit:missing`: Radar detected units at the address, but no unit was specified.
* `unit:invalid`: Radar detected units at the address, but the unit specified doesn't exist.
**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](/regions/countries) (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**
100 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**
```json theme={null}
{
"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. In the response, `distance.value` will be in meters for `metric` and in feet for `imperial`.
* `avoid` (string, optional): The features that calculated routes should avoid. A string, comma-separated, including one or more of `tolls`, `highways`, `ferries` and `borderCrossings`. No features are avoided if not provided.
* `geometry` (string, optional): The format of the `geometry` in the response. Valid values are `linestring`, `polyline5` and `polyline6`. `linestring` returns a GeoJSON `LineString`, `polyline5` returns a polyline with 5 decimal places of precision (compatible with other mapping providers) and `polyline6` returns a polyline with 6 decimal places of precision. Defaults to none if not provided.
* `departureTime` (string, optional): The date and time of the route provided as an ISO 8601 date string (e.g., `2025-01-01T14:30:00Z`) which will be used for historical traffic times. If not provided, the current date and time will be used.
**Authentication level**
Publishable
**Default rate limit**
100 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**
```json theme={null}
{
"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 625 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.
* `departureTime` (string, optional): The date and time of the route provided as an ISO 8601 date string (e.g., `2025-01-01T14:30:00Z`) which will be used for historical traffic times. If not provided, the current date and time will be used.
**Authentication level**
Publishable
**Default rate limit**
20 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**
```json theme={null}
{
"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**
`POST https://api.radar.io/v1/route/match`
**JSON payload**
* `path` (array, required): A list of coordinate objects along a route to be snapped.
* Each object in the list should be of the form `{"coordinates": "latitude,longitude"}`
* Objects may optionally include either or both an ISO date string and an accuracy value in meters for that coordinate `{"coordinates": "latitude,longitude", "createdAt": "iso date string", "accuracy": value}`
* `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.
* `geometry` (string, optional): The format of the `geometry` in the response. Valid values are `linestring`, `polyline5` and `polyline6`. `linestring` returns a GeoJSON `LineString`, `polyline5` returns a polyline with 5 decimal places of precision (compatible with other mapping providers) and `polyline6` returns a polyline with 6 decimal places of precision. Defaults to `polyline6` if not provided.
**Authentication level**
Publishable
**Default rate limit**
10 requests per second (contact your customer success manager to increase rate limit)
**Sample request**
```
curl "https://api.radar.io/v1/route/match" \
-H "Authorization: prj_live_pk_..." \
-H "Content-Type: application/json" \
-X POST \
-d '{"path": [{"coordinates": "40.754231505412264,-73.98465161242224", "createdAt": "2024-03-29T20:47:49Z", "accuracy": 23}, {"coordinates": "40.73988226756973,-73.9950818342906", "createdAt": "2024-03-29T20:49:02Z", "accuracy": 27}], "mode": "car", "roadAttributes": "speedLimit,names,roadClass"}'
```
**Sample response**
```json theme={null}
{
"meta": {
"code": 200
},
"matchedPath": [
{
"latitude": 40.754233,
"longitude": -73.984727,
"originalIndex": 0
},
{
"latitude": 40.739919,
"longitude": -73.995156,
"originalIndex": 1
}
],
"roadAttributes": [
{
"roadClass": "residential",
"speedLimit": {
"value": 25,
"text": "25 mph"
},
"names": [
"West 41st Street"
],
"startLocation": {
"latitude": 40.754233,
"longitude": -73.984728
},
"endLocation": {
"latitude": 40.754464,
"longitude": -73.985276
},
"originalIndex": 0
},
{
"roadClass": "secondary",
"speedLimit": {
"value": 25,
"text": "25 mph"
},
"names": [
"7th Avenue"
],
"startLocation": {
"latitude": 40.755373,
"longitude": -73.987447
},
"endLocation": {
"latitude": 40.75532,
"longitude": -73.987485
}
},
{
"roadClass": "residential",
"speedLimit": {
"value": 25,
"text": "25 mph"
},
"names": [
"West 18th Street"
],
"startLocation": {
"latitude": 40.741056,
"longitude": -73.997862
},
"endLocation": {
"latitude": 40.740997,
"longitude": -73.997721
}
},
{
"roadClass": "residential",
"speedLimit": {
"value": 25,
"text": "25 mph"
},
"names": [
"West 18th Street"
],
"startLocation": {
"latitude": 40.740997,
"longitude": -73.997721
},
"endLocation": {
"latitude": 40.739919,
"longitude": -73.995157
},
"originalIndex": 1
}
],
"geometry": {
"polyline": "qbmvlAnltblCmMfa@Wx@mApDYz@s@xBcZd_Ag@|Aw@fCc@vA{AvE}Lba@cBrFhBjAbQ|KtLvHnBnAlBnAl]vTbC|AtClBj]jUdDzB|AbAt]nUjCdBhBlA`^vUnBrA`CxAl^hUzBvAlBpAz^lVhDzBnEvCz^dVhBnAjCbB~AdA`ZxRTNrCjBxA`At@d@n\\tTxBvA`C|Az]hUpChBlBtAh]pVpBpAjCdBvOhJrFdDxErCPLrBrAnBpAvQtL|JvGlCdBnBpAhUhOvGjEvBxAvBtA~]hUbC|AfBjAxUrOdG|DjCfBrBrAlD|BtJpGjMjI`EjCbEnCFDnO~JlNfJzBxAzBtAb^vUvBtAfBjAtTvNxFxDtBvAjBnA`\\bTdC`BbBfArTrN`G`ExBxAtByGjbAg_D"
},
"distance": {
"value": 7439.501747250396,
"text": "1.4 mi"
}
}
```
**Response Definitions**
`roadClass` values, in descending order of size:
* `motorway`: Major divided highway, normally with 2 or more running lanes plus emergency hard shoulder.
* `trunk`: Arterial roads meant to support large amounts of traffic.
* `primary`: Large sized roads.
* `secondary`: Medium sized roads.
* `tertiary`: Small roads that often connect `residential` roads.
* `residential`: Roads which serve as an access to housing.
* `unclassified`: Minor roads that don't provide access to housing.
* `service_other`: For access roads to, or within an industrial estate, camp site, business park, car park, alleys, etc.
#### **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`, `ferries` and `borderCrossings`. No features are avoided if not provided.
* `geometry` (string, optional): The format of the `geometry` in the response. Valid values are `linestring`, `polyline5` and `polyline6`. `linestring` returns a GeoJSON `LineString`, `polyline5` returns a polyline with 5 decimal places of precision (compatible with other mapping providers) and `polyline6` returns a polyline with 6 decimal places of precision. Defaults to `polyline6` if not provided.
* `departureTime` (string, optional): The date and time of the route provided as an ISO 8601 date string (e.g., `2025-01-01T14:30:00Z`) which will be used for historical traffic times. If not provided, the current date and time will be used.
* `heading` (number, optional): Initial heading of travel where north is 0°, east is 90°, south is 180°, and west is 270°. If not provided, no initial heading will be used.
**Turn by Turn**
Additionally you can modify the turn-by-turn directions response by specifying additional query parameters.
* `alternatives` (boolean, optional): Specifies whether to try to return alternative routes. This feature is available if only two locations are specified. Defaults to `false`.
* `lang` (string, optional): Specifies the language for the results. A string, one of `de`, `en`, `es`, `fr`, `ja`, `ko`, `pt`, `ru`. Defaults to `en`.
**Authentication level**
Publishable
**Default rate limit**
10 requests per second (contact your customer success manager to increase rate limit)
**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**
```json theme={null}
{
"meta": {
"code": 200
},
"routes": [
{
"duration": {
"value": 52.07845,
"text": "52 mins"
},
"distance": {
"value": 62683.72904,
"text": "11.9 mi"
},
"legs": [
{
"startLocation": {
"latitude": 40.73425,
"longitude": -73.990934
},
"endLocation": {
"latitude": 40.712971,
"longitude": -73.951385
},
"duration": {
"value": 20.394166666666667,
"text": "20 mins"
},
"distance": {
"value": 19639.10824,
"text": "3.7 mi"
},
"geometry": {
"polyline": "kafulAnn`clCfKxAhCF`CJdg@vGtB\\|BZfJrAh[lEhC^dBThMjBjRjCdBZn@Pd@Nh@PzAuE|EoO`HqT`CuHl@mBbCkHxBkGhYk}@v@oCfBuFvB_H~c@avAbLm^ZgAj@kB`BmFlBnAvYlRjAv@nBrAdC~AvVdPdEnCfBhAtBvAj^~UrBtAlBnAn\\dTbBfAtBtAl^zUzAbAjCfBv]tUbBfAjBlAf^pUhBlAnBnAfSzMhLxHrBrAlBrAlFnDzXnRnBrAtBxAjFfDtFx@jEZ|BRzDh@xFtAjD`AvAj@|Ap@lQnH~ZjMhIhDzAl@bBp@nBt@pAh@l{@r]xAf@rBr@xAf@vAd@xItDbVrKvVjKz@^hBr@rEdBzGlC`AwEX}AnG}Zd@}B~@uEj@uCtKyh@XsAh@gCd@yBbJ{c@\\aBr@iD~AeIz@yDn@wCpD}PVmAf@eCf@eC`Joc@VsAf@aCd@}BpHm^r@kDXoAfAkFbA{EtIsb@Z}A`@uBR_AXeAd@}A`AwCtEsNrAsEjAeEb@aBd@aBr@sCz@cDjBcHbIoY|@kD\\qAXkAxDgRzAmHzSgdA~J_g@|\\gcBpb@_uB|U{kAlDqUxWysA`~DirRd_@ufBrJk^ts@spDzH{TrEcU`AoFjCkOd@yC`@}CToCTwChAeTx@}PRkCb@eDd@gCn@sCrP_r@\\wAjAsEmCuAsP}I}KsG}@i@kAq@QeFo@uTAMiBy_@wBac@KkBOkBQiDk@mIs@{Io@aMmBs]{AmXS}EQ{CoBac@OeDeA{ScAoTUmEUeEsA{X}@yPoAcW_Cef@WkF}AcPScFG}AUkFaDXg[dCmKx@aCRec@hD_CP{CZo]bD"
},
"steps": [
{
"distance": {
"value": 931.75856,
"text": "0.2 mi"
},
"duration": {
"value": 1.4142833333333333,
"text": "1 min"
},
"start_location": {
"latitude": 40.734246,
"longitude": -73.990904
},
"end_location": {
"latitude": 40.731744,
"longitude": -73.991464
},
"bearing_before": 0,
"bearing_after": 189,
"instructions": "Drive south on Broadway. Then, in 300 meters, Turn left onto East 10th Street.",
"banner_instructions": "Drive south on Broadway.",
"voice_instructions": "Drive south on Broadway.",
"geometry": {
"polyline": "kafulAnn`clCfKxAhCF`CJdg@vGtB\\|BZfJrAh[lEhC^dBThMjBjRjCdBZn@Pd@Nh@P"
},
"mode": "car",
"manuever": "start",
"street_name": "Broadway"
},
{
"distance": {
"value": 1473.09716,
"text": "0.3 mi"
},
"duration": {
"value": 2.5110666666666663,
"text": "3 mins"
},
"start_location": {
"latitude": 40.731744,
"longitude": -73.991464
},
"end_location": {
"latitude": 40.729779,
"longitude": -73.986812
},
"bearing_before": 197,
"bearing_after": 119,
"instructions": "Turn left onto East 10th Street.",
"banner_instructions": "Turn left onto East 10th Street.",
"voice_instructions": "Turn left onto East 10th Street.",
"geometry": {
"polyline": "_eaulAnqaclCzAuE|EoO`HqT`CuHl@mBbCkHxBkGhYk}@v@oCfBuFvB_H~c@avAbLm^ZgAj@kB`BmF"
},
"mode": "car",
"manuever": "left",
"street_name": "East 10th Street"
},
{
"distance": {
"value": 3992.78228,
"text": "0.8 mi"
},
"duration": {
"value": 4.9593,
"text": "5 mins"
},
"start_location": {
"latitude": 40.729779,
"longitude": -73.986812
},
"end_location": {
"latitude": 40.719911,
"longitude": -73.992948
},
"bearing_before": 118,
"bearing_after": 208,
"instructions": "Turn right onto 2nd Avenue.",
"banner_instructions": "Turn right onto 2nd Avenue.",
"voice_instructions": "Turn right onto 2nd Avenue.",
"geometry": {
"polyline": "ej}tlAvnxblClBnAvYlRjAv@nBrAdC~AvVdPdEnCfBhAtBvAj^~UrBtAlBnAn\\dTbBfAtBtAl^zUzAbAjCfBv]tUbBfAjBlAf^pUhBlAnBnAfSzMhLxHrBrAlBrAlFnDzXnRnBrAtBxAjFfDtFx@jEZ|BRzDh@xFtAjD`AvAj@|Ap@lQnH~ZjMhIhDzAl@bBp@nBt@pAh@l{@r]xAf@rBr@xAf@vAd@xItDbVrKvVjKz@^hBr@rEdBzGlC"
},
"mode": "car",
"manuever": "right",
"street_name": "2nd Avenue"
},
{
"distance": {
"value": 4215.8794,
"text": "0.8 mi"
},
"duration": {
"value": 5.349966666666666,
"text": "5 mins"
},
"start_location": {
"latitude": 40.719911,
"longitude": -73.992948
},
"end_location": {
"latitude": 40.715536,
"longitude": -73.978895
},
"bearing_before": 200,
"bearing_after": 111,
"instructions": "Turn left onto Delancey Street.",
"banner_instructions": "Turn left onto Delancey Street.",
"voice_instructions": "Turn left onto Delancey Street.",
"geometry": {
"polyline": "majtlAfndclC`AwEX}AnG}Zd@}B~@uEj@uCtKyh@XsAh@gCd@yBbJ{c@\\aBr@iD~AeIz@yDn@wCpD}PVmAf@eCf@eC`Joc@VsAf@aCd@}BpHm^r@kDXoAfAkFbA{EtIsb@Z}A`@uBR_AXeAd@}A`AwCtEsNrAsEjAeEb@aBd@aBr@sCz@cDjBcHbIoY|@kD\\qAXkAxDgRzAmHzSgdA~J_g@|\\gcBpb@_uB|U{kA"
},
"mode": "car",
"manuever": "left",
"street_name": "Delancey Street"
},
{
"distance": {
"value": 5000.00016,
"text": "0.9 mi"
},
"duration": {
"value": 1.6442666666666668,
"text": "2 mins"
},
"start_location": {
"latitude": 40.715536,
"longitude": -73.978895
},
"end_location": {
"latitude": 40.710451,
"longitude": -73.962137
},
"bearing_before": 111,
"bearing_after": 107,
"instructions": "Keep left to take Interstate 2 78 East toward Queens, Bronx.",
"banner_instructions": "Keep left to take I 278 East toward Queens/Bronx.",
"voice_instructions": "Keep left to take I 278 East toward Queens/Bronx.",
"geometry": {
"polyline": "_patlA|_iblClDqUxWysA`~DirRd_@ufBrJk^ts@spD"
},
"mode": "car",
"manuever": "stay-left",
"street_name": "Williamsburg Bridge"
},
{
"distance": {
"value": 213.2546,
"text": "213.3 ft"
},
"duration": {
"value": 0.07093333333333333,
"text": "0.1 min"
},
"start_location": {
"latitude": 40.710451,
"longitude": -73.962137
},
"end_location": {
"latitude": 40.710187,
"longitude": -73.961433
},
"bearing_before": 111,
"bearing_after": 120,
"instructions": "Keep right toward Interstate 2 78 West, Broadway West. Then Keep left toward Broadway East.",
"banner_instructions": "Keep right toward I 278 West/Broadway West.",
"voice_instructions": "Keep right toward I 278 West/Broadway West.",
"geometry": {
"polyline": "erwslAphhalCzH{TrEcU"
},
"mode": "car",
"manuever": "stay-right",
"street_name": "I 278 West/Broadway West"
},
{
"distance": {
"value": 757.87404,
"text": "757.9 ft"
},
"duration": {
"value": 0.6236166666666667,
"text": "1 min"
},
"start_location": {
"latitude": 40.710187,
"longitude": -73.961433
},
"end_location": {
"latitude": 40.709554,
"longitude": -73.95886
},
"bearing_before": 111,
"bearing_after": 109,
"instructions": "Keep left toward Broadway East, South 5th Street.",
"banner_instructions": "Keep left toward Broadway East/South 5th Street.",
"voice_instructions": "Keep left toward Broadway East/South 5th Street.",
"geometry": {
"polyline": "uawslAp|falC`AoFjCkOd@yC`@}CToCTwChAeTx@}PRkCb@eDd@gCn@sCrP_r@\\wAjAsE"
},
"mode": "car",
"manuever": "stay-left",
"street_name": "Broadway East/South 5th Street"
},
{
"distance": {
"value": 259.18636,
"text": "259.2 ft"
},
"duration": {
"value": 0.5566333333333334,
"text": "1 min"
},
"start_location": {
"latitude": 40.709554,
"longitude": -73.95886
},
"end_location": {
"latitude": 40.710183,
"longitude": -73.958458
},
"bearing_before": 115,
"bearing_after": 24,
"instructions": "Turn left onto Havemeyer Street. Then Turn right onto Borinquen Place.",
"banner_instructions": "Turn left onto Havemeyer Street.",
"voice_instructions": "Turn left onto Havemeyer Street.",
"geometry": {
"polyline": "czuslAv{aalCmCuAsP}I}KsG}@i@kAq@"
},
"mode": "car",
"manuever": "left",
"street_name": "Havemeyer Street"
},
{
"distance": {
"value": 2050.525,
"text": "0.4 mi"
},
"duration": {
"value": 1.8798333333333335,
"text": "2 mins"
},
"start_location": {
"latitude": 40.710183,
"longitude": -73.958458
},
"end_location": {
"latitude": 40.710961,
"longitude": -73.951119
},
"bearing_before": 26,
"bearing_after": 84,
"instructions": "Turn right onto Borinquen Place.",
"banner_instructions": "Turn right onto Borinquen Place.",
"voice_instructions": "Turn right onto Borinquen Place.",
"geometry": {
"polyline": "mawslArbaalCQeFo@uTAMiBy_@wBac@KkBOkBQiDk@mIs@{Io@aMmBs]{AmXS}EQ{CoBac@OeDeA{ScAoTUmEUeEsA{X}@yPoAcW_Cef@WkF}AcPScFG}AUkF"
},
"mode": "car",
"manuever": "right",
"street_name": "Borinquen Place"
},
{
"distance": {
"value": 734.90816,
"text": "734.9 ft"
},
"duration": {
"value": 1.3842166666666667,
"text": "1 min"
},
"start_location": {
"latitude": 40.710961,
"longitude": -73.951119
},
"end_location": {
"latitude": 40.712967,
"longitude": -73.951428
},
"bearing_before": 82,
"bearing_after": 353,
"instructions": "Turn left onto Union Avenue.",
"banner_instructions": "Turn left onto Union Avenue.",
"voice_instructions": "Turn left onto Union Avenue.",
"geometry": {
"polyline": "arxslA|wr`lCaDXg[dCmKx@aCRec@hD_CP{CZo]bD"
},
"mode": "car",
"manuever": "left",
"street_name": "Union Avenue"
},
{
"distance": {
"value": 0,
"text": "0.0 ft"
},
"duration": {
"value": 0,
"text": "0 min"
},
"start_location": {
"latitude": 40.712967,
"longitude": -73.951428
},
"end_location": {
"latitude": 40.712967,
"longitude": -73.951428
},
"bearing_before": 352,
"bearing_after": 0,
"instructions": "You have arrived at your destination.",
"banner_instructions": "You have arrived at your destination.",
"voice_instructions": "You have arrived at your destination.",
"geometry": {
"polyline": "mo|slAfks`lC"
},
"mode": "car",
"manuever": "destination"
}
]
},
{
"startLocation": {
"latitude": 40.712971,
"longitude": -73.951385
},
"endLocation": {
"latitude": 40.74558,
"longitude": -73.903162
},
"duration": {
"value": 20.06063333333333,
"text": "20 mins"
},
"distance": {
"value": 21571.523,
"text": "4.1 mi"
},
"geometry": {
"polyline": "mo|slAfks`lCyGn@wk@tGgIz@}CTwDVuVnByXvB_DX}CwDqNeTkt@yhAkKiR}BoDiBeDsZoj@oY}f@cBaDqBkDsVyc@y^mo@_B_DsAmCqJcRuKiTaV{`@oBwC}AuCoc@}{@{CsGeBgDkm@wnA{AsCaB_DkJySiCsFiCuFuBgEYk@iBmDyAyC{AgC_CqDsLaRyG}KmDeGmDwFgC_EiNyTcCuDcCeEyC_GwCoGsSse@_DwGsBmEsBoEsHePaCoFgBsEiBgFqBmFcB}FsAsFyAgGyAmGoAmG{AmHqAyGeFwX{@yEkCcPuBsMyBkOqSstAsDgWgKos@aAuGcC{NeA_GuAeHqAoGqAeG}A}GcBwG_KoU_CcH}BsGiBeFuCeHmCiG{CwGoCsFkCkFwCkFqCmE{CaFwCmE{CiEqEeGocBctBiI_KcHuIiGsHuEaFeFuFcEgEoEkE{FoFkFuEmGaFwEoD}EoDqFaE{GyEoFoDuEuCgEmCoaAwk@ef@qVam@o]oFeDyEsC}DkCsDiCqFiEgFwE}E}E}DmEiD}DuDwE}DsF{DiGoDiGuCsFcDyGgEwJ_MiYy@gCyDqMcDyLgEwMqBoJmB_JkBsImAcHaBiJmAoHiA{GcAwG}@iGu@uFw@{Gw@mGu@qHs@sH_A{L{@uQeAcQy@yPo@qPi@iQ_Bml@[aPu@kQ_AiP}}@s{McB}Wi@mHs@qHu@wHm@eFy@uG{@eGaAsGaAeGkAoGkAcGuAoGuAeGsAuFaBeGaByFcBuFmB}Fwd@{sAqEqM}E_OsE_OwDoM_@wAcCiJy@{CSw@uBcIcHmXwEo_@yEcZgAeF{AwFuAmEqAyDsPad@iC{GuHwRiCyLsFsP[_Cq@kFwCQySeBiU{B_DSmHw@kHu@{BW{Ek@sEk@oDe@mEk@}BW{AQwJiAcq@{HoYkD{m@uHuCa@w@~DWpAsDrRkFbYu@jDq@pCyGvWmGxYwB|H{DlNY`Ai@pBkGrWmHdYiEfWiIhf@sD~Tk@bDeDaAq]kKcFiBUiEYgG"
},
"steps": [
{
"distance": {
"value": 757.87404,
"text": "757.9 ft"
},
"duration": {
"value": 1.42635,
"text": "1 min"
},
"start_location": {
"latitude": 40.712967,
"longitude": -73.951428
},
"end_location": {
"latitude": 40.715031,
"longitude": -73.951773
},
"bearing_before": 0,
"bearing_after": 352,
"instructions": "Drive north on Union Avenue. Then, in 200 meters, Turn right onto Meeker Avenue.",
"banner_instructions": "Drive north on Union Avenue.",
"voice_instructions": "Drive north on Union Avenue.",
"geometry": {
"polyline": "mo|slAfks`lCyGn@wk@tGgIz@}CTwDVuVnByXvB_DX"
},
"mode": "car",
"manuever": "start",
"street_name": "Union Avenue"
},
{
"distance": {
"value": 5150.9188,
"text": "1.0 mi"
},
"duration": {
"value": 5.7953,
"text": "6 mins"
},
"start_location": {
"latitude": 40.715031,
"longitude": -73.951773
},
"end_location": {
"latitude": 40.723834,
"longitude": -73.937366
},
"bearing_before": 352,
"bearing_after": 41,
"instructions": "Turn right onto Meeker Avenue.",
"banner_instructions": "Turn right onto Meeker Avenue.",
"voice_instructions": "Turn right onto Meeker Avenue.",
"geometry": {
"polyline": "mp`tlAx`t`lC}CwDqNeTkt@yhAkKiR}BoDiBeDsZoj@oY}f@cBaDqBkDsVyc@y^mo@_B_DsAmCqJcRuKiTaV{`@oBwC}AuCoc@}{@{CsGeBgDkm@wnA{AsCaB_DkJySiCsFiCuFuBgEYk@iBmDyAyC{AgC_CqDsLaRyG}KmDeGmDwFgC_EiNyTcCuDcCeEyC_GwCoGsSse@_DwGsBmEsBoEsHePaCoFgBsEiBgFqBmFcB}FsAsFyAgGyAmGoAmG{AmHqAyG"
},
"mode": "car",
"manuever": "right",
"street_name": "Meeker Avenue"
},
{
"distance": {
"value": 4366.79804,
"text": "0.8 mi"
},
"duration": {
"value": 2.5965,
"text": "3 mins"
},
"start_location": {
"latitude": 40.723834,
"longitude": -73.937366
},
"end_location": {
"latitude": 40.731092,
"longitude": -73.92567
},
"bearing_before": 69,
"bearing_after": 69,
"instructions": "Take the Interstate 2 78 East ramp on the left toward Brooklyn-Queens Expressway, Queens.",
"banner_instructions": "Take the I 278 East ramp on the left toward Brooklyn-Queens Expressway/Queens/Bronx.",
"voice_instructions": "Take the I 278 East ramp on the left toward Brooklyn-Queens Expressway/Queens/Bronx.",
"geometry": {
"polyline": "svqtlAj|w_lCeFwX{@yEkCcPuBsMyBkOqSstAsDgWgKos@aAuGcC{NeA_GuAeHqAoGqAeG}A}GcBwG_KoU_CcH}BsGiBeFuCeHmCiG{CwGoCsFkCkFwCkFqCmE{CaFwCmE{CiEqEeGocBctBiI_KcHuIiGsHuEaFeFuFcEgEoEkE{FoFkFuEmGaFwEoD}EoDqFaE{GyEoFoDuEuCgEmCoaAwk@"
},
"mode": "car",
"manuever": "ramp-left",
"street_name": "I 278 East/Brooklyn-Queens Expressway"
},
{
"distance": {
"value": 7165.35456,
"text": "1.4 mi"
},
"duration": {
"value": 5.1314166666666665,
"text": "5 mins"
},
"start_location": {
"latitude": 40.731092,
"longitude": -73.92567
},
"end_location": {
"latitude": 40.738404,
"longitude": -73.902957
},
"bearing_before": 27,
"bearing_after": 24,
"instructions": "Keep left to stay on Interstate 2 78 East, Brooklyn-Queens Expressway.",
"banner_instructions": "Keep left to stay on I 278 East/Brooklyn-Queens Expressway.",
"voice_instructions": "Keep left to stay on I 278 East/Brooklyn-Queens Expressway.",
"geometry": {
"polyline": "g|_ulAjaa_lCef@qVam@o]oFeDyEsC}DkCsDiCqFiEgFwE}E}E}DmEiD}DuDwE}DsF{DiGoDiGuCsFcDyGgEwJ_MiYy@gCyDqMcDyLgEwMqBoJmB_JkBsImAcHaBiJmAoHiA{GcAwG}@iGu@uFw@{Gw@mGu@qHs@sH_A{L{@uQeAcQy@yPo@qPi@iQ_Bml@[aPu@kQ_AiP}}@s{McB}Wi@mHs@qHu@wHm@eFy@uG{@eGaAsGaAeGkAoGkAcGuAoGuAeGsAuFaBeGaByFcBuFmB}Fwd@{sAqEqM}E_OsE_OwDoM_@wAcCiJy@{CSw@uBcIcHmX"
},
"mode": "car",
"manuever": "stay-left",
"street_name": "I 278 East/Brooklyn-Queens Expressway"
},
{
"distance": {
"value": 961.28612,
"text": "0.2 mi"
},
"duration": {
"value": 0.62875,
"text": "1 min"
},
"start_location": {
"latitude": 40.738404,
"longitude": -73.902957
},
"end_location": {
"latitude": 40.739523,
"longitude": -73.899832
},
"bearing_before": 64,
"bearing_after": 74,
"instructions": "Take exit 39 onto 65th Place.",
"banner_instructions": "Take exit 39 onto 65th Place.",
"voice_instructions": "Take exit 39 onto 65th Place.",
"geometry": {
"polyline": "genulAxut}kCwEo_@yEcZgAeF{AwFuAmEqAyDsPad@iC{GuHwRiCyLsFsP[_Cq@kF"
},
"mode": "car",
"manuever": "exit-right",
"street_name": "Laurel Hill Boulevard",
"exit_name": "39"
},
{
"distance": {
"value": 1459.9738,
"text": "0.3 mi"
},
"duration": {
"value": 1.9234166666666668,
"text": "2 mins"
},
"start_location": {
"latitude": 40.739523,
"longitude": -73.899832
},
"end_location": {
"latitude": 40.743487,
"longitude": -73.899074
},
"bearing_before": 74,
"bearing_after": 5,
"instructions": "Turn left onto 65th Place.",
"banner_instructions": "Turn left onto 65th Place.",
"voice_instructions": "Turn left onto 65th Place.",
"geometry": {
"polyline": "ekpulAnrn}kCwCQySeBiU{B_DSmHw@kHu@{BW{Ek@sEk@oDe@mEk@}BW{AQwJiAcq@{HoYkD{m@uHuCa@"
},
"mode": "car",
"manuever": "left",
"street_name": "65th Place"
},
{
"distance": {
"value": 1374.67196,
"text": "0.3 mi"
},
"duration": {
"value": 1.9673666666666667,
"text": "2 mins"
},
"start_location": {
"latitude": 40.743487,
"longitude": -73.899074
},
"end_location": {
"latitude": 40.744914,
"longitude": -73.903687
},
"bearing_before": 9,
"bearing_after": 291,
"instructions": "Turn left onto Woodside Avenue.",
"banner_instructions": "Turn left onto Woodside Avenue.",
"voice_instructions": "Turn left onto Woodside Avenue.",
"geometry": {
"polyline": "}bxulAbcm}kCw@~DWpAsDrRkFbYu@jDq@pCyGvWmGxYwB|H{DlNY`Ai@pBkGrWmHdYiEfWiIhf@sD~Tk@bD"
},
"mode": "car",
"manuever": "left",
"street_name": "Woodside Avenue"
},
{
"distance": {
"value": 262.4672,
"text": "262.5 ft"
},
"duration": {
"value": 0.4638,
"text": "0.5 min"
},
"start_location": {
"latitude": 40.744914,
"longitude": -73.903687
},
"end_location": {
"latitude": 40.7456,
"longitude": -73.903403
},
"bearing_before": 289,
"bearing_after": 16,
"instructions": "Turn right onto 61st Street. Then Turn right onto Roosevelt Avenue.",
"banner_instructions": "Turn right onto 61st Street.",
"voice_instructions": "Turn right onto 61st Street.",
"geometry": {
"polyline": "c|zulAlcv}kCeDaAq]kKcFiB"
},
"mode": "car",
"manuever": "right",
"street_name": "61st Street"
},
{
"distance": {
"value": 65.6168,
"text": "65.6 ft"
},
"duration": {
"value": 0.12766666666666668,
"text": "0.1 min"
},
"start_location": {
"latitude": 40.7456,
"longitude": -73.903403
},
"end_location": {
"latitude": 40.745624,
"longitude": -73.90317
},
"bearing_before": 19,
"bearing_after": 81,
"instructions": "Turn right onto Roosevelt Avenue. Then You will arrive at your destination.",
"banner_instructions": "Turn right onto Roosevelt Avenue.",
"voice_instructions": "Turn right onto Roosevelt Avenue.",
"geometry": {
"polyline": "_g|ulAtqu}kCUiEYgG"
},
"mode": "car",
"manuever": "right",
"street_name": "Roosevelt Avenue"
},
{
"distance": {
"value": 0,
"text": "0.0 ft"
},
"duration": {
"value": 0,
"text": "0 min"
},
"start_location": {
"latitude": 40.745624,
"longitude": -73.90317
},
"end_location": {
"latitude": 40.745624,
"longitude": -73.90317
},
"bearing_before": 82,
"bearing_after": 0,
"instructions": "You have arrived at your destination.",
"banner_instructions": "You have arrived at your destination.",
"voice_instructions": "You have arrived at your destination.",
"geometry": {
"polyline": "oh|ulAbcu}kC"
},
"mode": "car",
"manuever": "destination"
}
]
},
{
"startLocation": {
"latitude": 40.74558,
"longitude": -73.903162
},
"endLocation": {
"latitude": 40.774419,
"longitude": -73.872746
},
"duration": {
"value": 11.62365,
"text": "12 mins"
},
"distance": {
"value": 21473.0978,
"text": "4.1 mi"
},
"geometry": {
"polyline": "oh|ulAbcu}kCqEg_AwDiz@QaEOoCwDmu@ScEOyCkD{r@[oGQoDyAwXsAcX{Dkv@}Dew@wC\\ea@vEwAPgBTc_@jEqBTgCXg@Fef@pF_@D}C~@M}Cc@{Ke@}IoAqC_AaBeAy@kAm@oBg@s@UiAQcA?g@Pk@@_AZaAXu@\\qG~Cq^dRgHrDgHjDoI|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{EqNgFkNiFgNoFcNuF_NwFuMgGcNw{@glB_GiMeGyMsFmM}BuFuBkFuBwFoBqFqBuFmB}FcBqFgBcG{AyFcBgG}AkG{AaGuAkGqA_GqAqGoAoG{@kEqCq_@IgA}B_]UeEe@}Ic@}Ke@kL[yLKuMAwPBsNHkMH}K|D_oBHkED{ECuEM{FUuF]sF}@iJeFgi@[iDYwDIwDBmENeEb@gEd@gDv@wDr@kCfAaDfK_Y`Lq_@pw@g_BdTkc@t_@yq@fBaDz@iBh@sAf@_Bb@yATsARaBJgBFsBA}BK}BSuB]{Bo@yB}@}BeAmBoAaBiAmAuAeAqAs@sAc@_B]wAMyAEaBD}AX_Bd@uAp@}AbAoAdA_AbAw@bAmO|T{Rt[eHbMoAnC_AfCcB~EaBjFcAvDs@`Da@|B]bD]zDYjEUxEeDnr@[vE_@tEi@hEu@bFeAbFaAhEw@tCgAfD{BhGkBbEkDdH{GtNiH`OyLjVcC|GqCdIkCpI}CfKaB`GyA~FcBjH_BhIgA~GoAzIkAjJy@`Hu@fIm@hH]~F]|GWjIOhHIdHEtH?Z"
},
"steps": [
{
"distance": {
"value": 1909.44888,
"text": "0.4 mi"
},
"duration": {
"value": 2.5659,
"text": "3 mins"
},
"start_location": {
"latitude": 40.745624,
"longitude": -73.90317
},
"end_location": {
"latitude": 40.746333,
"longitude": -73.896325
},
"bearing_before": 0,
"bearing_after": 82,
"instructions": "Drive east on Roosevelt Avenue.",
"banner_instructions": "Drive east on Roosevelt Avenue.",
"voice_instructions": "Drive east on Roosevelt Avenue.",
"geometry": {
"polyline": "oh|ulAbcu}kCqEg_AwDiz@QaEOoCwDmu@ScEOyCkD{r@[oGQoDyAwXsAcX{Dkv@}Dew@"
},
"mode": "car",
"manuever": "start",
"street_name": "Roosevelt Avenue"
},
{
"distance": {
"value": 777.55908,
"text": "777.6 ft"
},
"duration": {
"value": 1.1424999999999998,
"text": "1 min"
},
"start_location": {
"latitude": 40.746333,
"longitude": -73.896325
},
"end_location": {
"latitude": 40.748433,
"longitude": -73.896754
},
"bearing_before": 82,
"bearing_after": 351,
"instructions": "Turn left onto 69th Street.",
"banner_instructions": "Turn left onto 69th Street.",
"voice_instructions": "Turn left onto 69th Street.",
"geometry": {
"polyline": "yt}ulAhwg}kCwC\\ea@vEwAPgBTc_@jEqBTgCXg@Fef@pF_@D}C~@"
},
"mode": "car",
"manuever": "left",
"street_name": "69th Street"
},
{
"distance": {
"value": 127.95276,
"text": "128.0 ft"
},
"duration": {
"value": 0.27251666666666663,
"text": "0.3 min"
},
"start_location": {
"latitude": 40.748433,
"longitude": -73.896754
},
"end_location": {
"latitude": 40.748477,
"longitude": -73.896294
},
"bearing_before": 342,
"bearing_after": 83,
"instructions": "Turn right onto 37th Avenue. Then Turn left to take the Interstate 2 78 East ramp.",
"banner_instructions": "Turn right onto 37th Avenue.",
"voice_instructions": "Turn right onto 37th Avenue.",
"geometry": {
"polyline": "axavlAbrh}kCM}Cc@{Ke@}I"
},
"mode": "car",
"manuever": "right",
"street_name": "37th Avenue"
},
{
"distance": {
"value": 2388.45152,
"text": "0.5 mi"
},
"duration": {
"value": 0.9872,
"text": "1 min"
},
"start_location": {
"latitude": 40.748477,
"longitude": -73.896294
},
"end_location": {
"latitude": 40.754551,
"longitude": -73.898787
},
"bearing_before": 81,
"bearing_after": 54,
"instructions": "Turn left to take the Interstate 2 78 East ramp toward Brooklyn Queens Expressway, LaGuardia.",
"banner_instructions": "Turn left to take the I 278 East ramp toward Brooklyn Queens Expressway/LaGuardia/Robert F. Kennedy Bridge.",
"voice_instructions": "Turn left to take the I 278 East ramp toward Brooklyn Queens Expressway/LaGuardia/Robert F. Kennedy Bridge.",
"geometry": {
"polyline": "yzavlAjug}kCoAqC_AaBeAy@kAm@oBg@s@UiAQcA?g@Pk@@_AZaAXu@\\qG~Cq^dRgHrDgHjDoI|D}G~CeGnCaDfA{DhAaE`AiEx@sNzFsHl@aVnAm_@nD}ShDaQ`EiQfIs~@vg@mc@|V}CfB"
},
"mode": "car",
"manuever": "ramp-left",
"street_name": "I 278 East/Brooklyn-Queens Expressway"
},
{
"distance": {
"value": 4025.59068,
"text": "0.8 mi"
},
"duration": {
"value": 1.3148833333333334,
"text": "1 min"
},
"start_location": {
"latitude": 40.754551,
"longitude": -73.898787
},
"end_location": {
"latitude": 40.764487,
"longitude": -73.894912
},
"bearing_before": 333,
"bearing_after": 342,
"instructions": "Keep right to take exit 42 to stay on Brooklyn-Queens Expressway East toward La Guardia Airport.",
"banner_instructions": "Keep right to take exit 42 to stay on Brooklyn-Queens Expressway East toward La Guardia Airport.",
"voice_instructions": "Keep right to take exit 42 to stay on Brooklyn-Queens Expressway East toward La Guardia Airport.",
"geometry": {
"polyline": "mvmvlAdql}kCkZbJaa@pM_UlGwWpFkGxAe^|GkS`BaMz@qLQuM{@wQeDwM}DeNeFqQkGwg@q[e^_Ti_C}wA}l@i`@sE_DuDsCsDaDyDeEwCkDuCyD_DwEkLqRmCwDuDuEoDeE{CuC{CoC}EkDaAm@wBsAmF_C"
},
"mode": "car",
"manuever": "stay-right",
"street_name": "Brooklyn-Queens Expressway East",
"exit_name": "42"
},
{
"distance": {
"value": 5774.2784,
"text": "1.1 mi"
},
"duration": {
"value": 2.5493333333333337,
"text": "3 mins"
},
"start_location": {
"latitude": 40.764487,
"longitude": -73.894912
},
"end_location": {
"latitude": 40.771256,
"longitude": -73.876885
},
"bearing_before": 22,
"bearing_after": 15,
"instructions": "Keep left to take GCP, Grand Central Parkway.",
"banner_instructions": "Keep left to take GCP/Grand Central Parkway.",
"voice_instructions": "Keep left to take GCP/Grand Central Parkway.",
"geometry": {
"polyline": "mcawlA~~d}kCuDcAwEuAyQkEoEuAsDoAeD}A}CsBkCsByCyC}DqEiCyD}BsEuBwEeBmFkAkEeAaFs@_Gg@kG[sFSsHaAyh@c@eRm@cRcCyl@kAcVqIqs@{A_Q_B{PaBgPgBwPmBoPuBkPwBcPiCoQsBuMeCwOoC}OyCiPqCyO{C_PcDaPcDsOiDoOqDoOuDkO_EqOiEaOcEaOoE_OuE_O}E{N{EqNgFkNiFgNoFcNuF_NwFuMgGcNw{@glB_GiMeGyMsFmM}BuFuBkFuBwFoBqFqBuFmB}FcBqFgBcG{AyFcBgG}AkG{AaGuAkGqA_GqAqGoAoG{@kE"
},
"mode": "car",
"manuever": "stay-left",
"street_name": "GCP/Grand Central Parkway"
},
{
"distance": {
"value": 2906.82424,
"text": "0.6 mi"
},
"duration": {
"value": 1.0503500000000001,
"text": "1 min"
},
"start_location": {
"latitude": 40.771256,
"longitude": -73.876885
},
"end_location": {
"latitude": 40.770136,
"longitude": -73.867012
},
"bearing_before": 68,
"bearing_after": 79,
"instructions": "Take exit 7 toward LaGuardia Airport, Terminals B-C.",
"banner_instructions": "Take exit 7 toward LaGuardia Airport/Terminals B-C.",
"voice_instructions": "Take exit 7 toward LaGuardia Airport/Terminals B-C.",
"geometry": {
"polyline": "ojnwlAhxa|kCqCq_@IgA}B_]UeEe@}Ic@}Ke@kL[yLKuMAwPBsNHkMH}K|D_oBHkED{ECuEM{FUuF]sF}@iJeFgi@[iDYwDIwDBmENeEb@gEd@gDv@wDr@kCfAaDfK_Y`Lq_@pw@g_B"
},
"mode": "car",
"manuever": "exit-right",
"street_name": "LaGuardia Road",
"exit_name": "7"
},
{
"distance": {
"value": 1489.50136,
"text": "0.3 mi"
},
"duration": {
"value": 0.5813166666666666,
"text": "1 min"
},
"start_location": {
"latitude": 40.770136,
"longitude": -73.867012
},
"end_location": {
"latitude": 40.770698,
"longitude": -73.865902
},
"bearing_before": 127,
"bearing_after": 127,
"instructions": "Take the exit on the left toward Terminal B, Parking B.",
"banner_instructions": "Take the exit on the left toward Terminal B/Parking B/Rental Car Return.",
"voice_instructions": "Take the exit on the left toward Terminal B/Parking B/Rental Car Return.",
"geometry": {
"polyline": "odlwlAfon{kCdTkc@t_@yq@fBaDz@iBh@sAf@_Bb@yATsARaBJgBFsBA}BK}BSuB]{Bo@yB}@}BeAmBoAaBiAmAuAeAqAs@sAc@_B]wAMyAEaBD}AX_Bd@uAp@}AbAoAdA_AbAw@bAmO|T{Rt[eHbMoAnC_AfC"
},
"mode": "car",
"manuever": "exit-left",
"street_name": "Terminal B/Parking B/Rental Car Return"
},
{
"distance": {
"value": 2066.9292,
"text": "0.4 mi"
},
"duration": {
"value": 1.1596,
"text": "1 min"
},
"start_location": {
"latitude": 40.770698,
"longitude": -73.865902
},
"end_location": {
"latitude": 40.772666,
"longitude": -73.872746
},
"bearing_before": 301,
"bearing_after": 300,
"instructions": "Keep right to take Terminal B Arrivals toward Terminal B Arrivals.",
"banner_instructions": "Keep right to take Terminal B Arrivals toward Terminal B Arrivals.",
"voice_instructions": "Keep right to take Terminal B Arrivals toward Terminal B Arrivals.",
"geometry": {
"polyline": "sgmwlAzil{kCcB~EaBjFcAvDs@`Da@|B]bD]zDYjEUxEeDnr@[vE_@tEi@hEu@bFeAbFaAhEw@tCgAfD{BhGkBbEkDdH{GtNiH`OyLjVcC|GqCdIkCpI}CfKaB`GyA~FcBjH_BhIgA~GoAzIkAjJy@`Hu@fIm@hH]~F]|GWjIOhHIdHEtH?Z"
},
"mode": "car",
"manuever": "stay-right",
"street_name": "Terminal B Arrivals"
},
{
"distance": {
"value": 0,
"text": "0.0 ft"
},
"duration": {
"value": 0,
"text": "0 min"
},
"start_location": {
"latitude": 40.772666,
"longitude": -73.872746
},
"end_location": {
"latitude": 40.772666,
"longitude": -73.872746
},
"bearing_before": 270,
"bearing_after": 0,
"instructions": "Your destination is on the right.",
"banner_instructions": "Your destination is on the right.",
"voice_instructions": "Your destination is on the right.",
"geometry": {
"polyline": "sbqwlAruy{kC"
},
"mode": "car",
"manuever": "destination-right"
}
]
}
],
"geometry": {
"polyline": "kafulAnn`clCfKxAhCF`CJdg@vGtB\\|BZfJrAh[lEhC^dBThMjBjRjCdBZn@Pd@Nh@PzAuE|EoO`HqT`CuHl@mBbCkHxBkGhYk}@v@oCfBuFvB_H~c@avAbLm^ZgAj@kB`BmFlBnAvYlRjAv@nBrAdC~AvVdPdEnCfBhAtBvAj^~UrBtAlBnAn\\dTbBfAtBtAl^zUzAbAjCfBv]tUbBfAjBlAf^pUhBlAnBnAfSzMhLxHrBrAlBrAlFnDzXnRnBrAtBxAjFfDtFx@jEZ|BRzDh@xFtAjD`AvAj@|Ap@lQnH~ZjMhIhDzAl@bBp@nBt@pAh@l{@r]xAf@rBr@xAf@vAd@xItDbVrKvVjKz@^hBr@rEdBzGlC`AwEX}AnG}Zd@}B~@uEj@uCtKyh@XsAh@gCd@yBbJ{c@\\aBr@iD~AeIz@yDn@wCpD}PVmAf@eCf@eC`Joc@VsAf@aCd@}BpHm^r@kDXoAfAkFbA{EtIsb@Z}A`@uBR_AXeAd@}A`AwCtEsNrAsEjAeEb@aBd@aBr@sCz@cDjBcHbIoY|@kD\\qAXkAxDgRzAmHzSgdA~J_g@|\\gcBpb@_uB|U{kAlDqUxWysA`~DirRd_@ufBrJk^ts@spDzH{TrEcU`AoFjCkOd@yC`@}CToCTwChAeTx@}PRkCb@eDd@gCn@sCrP_r@\\wAjAsEmCuAsP}I}KsG}@i@kAq@QeFo@uTAMiBy_@wBac@KkBOkBQiDk@mIs@{Io@aMmBs]{AmXS}EQ{CoBac@OeDeA{ScAoTUmEUeEsA{X}@yPoAcW_Cef@WkF}AcPScFG}AUkFaDXg[dCmKx@aCRec@hD_CP{CZo]bDyGn@wk@tGgIz@}CTwDVuVnByXvB_DX}CwDqNeTkt@yhAkKiR}BoDiBeDsZoj@oY}f@cBaDqBkDsVyc@y^mo@_B_DsAmCqJcRuKiTaV{`@oBwC}AuCoc@}{@{CsGeBgDkm@wnA{AsCaB_DkJySiCsFiCuFuBgEYk@iBmDyAyC{AgC_CqDsLaRyG}KmDeGmDwFgC_EiNyTcCuDcCeEyC_GwCoGsSse@_DwGsBmEsBoEsHePaCoFgBsEiBgFqBmFcB}FsAsFyAgGyAmGoAmG{AmHqAyGeFwX{@yEkCcPuBsMyBkOqSstAsDgWgKos@aAuGcC{NeA_GuAeHqAoGqAeG}A}GcBwG_KoU_CcH}BsGiBeFuCeHmCiG{CwGoCsFkCkFwCkFqCmE{CaFwCmE{CiEqEeGocBctBiI_KcHuIiGsHuEaFeFuFcEgEoEkE{FoFkFuEmGaFwEoD}EoDqFaE{GyEoFoDuEuCgEmCoaAwk@ef@qVam@o]oFeDyEsC}DkCsDiCqFiEgFwE}E}E}DmEiD}DuDwE}DsF{DiGoDiGuCsFcDyGgEwJ_MiYy@gCyDqMcDyLgEwMqBoJmB_JkBsImAcHaBiJmAoHiA{GcAwG}@iGu@uFw@{Gw@mGu@qHs@sH_A{L{@uQeAcQy@yPo@qPi@iQ_Bml@[aPu@kQ_AiP}}@s{McB}Wi@mHs@qHu@wHm@eFy@uG{@eGaAsGaAeGkAoGkAcGuAoGuAeGsAuFaBeGaByFcBuFmB}Fwd@{sAqEqM}E_OsE_OwDoM_@wAcCiJy@{CSw@uBcIcHmXwEo_@yEcZgAeF{AwFuAmEqAyDsPad@iC{GuHwRiCyLsFsP[_Cq@kFwCQySeBiU{B_DSmHw@kHu@{BW{Ek@sEk@oDe@mEk@}BW{AQwJiAcq@{HoYkD{m@uHuCa@w@~DWpAsDrRkFbYu@jDq@pCyGvWmGxYwB|H{DlNY`Ai@pBkGrWmHdYiEfWiIhf@sD~Tk@bDeDaAq]kKcFiBUiEYgGqEg_AwDiz@QaEOoCwDmu@ScEOyCkD{r@[oGQoDyAwXsAcX{Dkv@}Dew@wC\\ea@vEwAPgBTc_@jEqBTgCXg@Fef@pF_@D}C~@M}Cc@{Ke@}IoAqC_AaBeAy@kAm@oBg@s@UiAQcA?g@Pk@@_AZaAXu@\\qG~Cq^dRgHrDgHjDoI|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{EqNgFkNiFgNoFcNuF_NwFuMgGcNw{@glB_GiMeGyMsFmM}BuFuBkFuBwFoBqFqBuFmB}FcBqFgBcG{AyFcBgG}AkG{AaGuAkGqA_GqAqGoAoG{@kEqCq_@IgA}B_]UeEe@}Ic@}Ke@kL[yLKuMAwPBsNHkMH}K|D_oBHkED{ECuEM{FUuF]sF}@iJeFgi@[iDYwDIwDBmENeEb@gEd@gDv@wDr@kCfAaDfK_Y`Lq_@pw@g_BdTkc@t_@yq@fBaDz@iBh@sAf@_Bb@yATsARaBJgBFsBA}BK}BSuB]{Bo@yB}@}BeAmBoAaBiAmAuAeAqAs@sAc@_B]wAMyAEaBD}AX_Bd@uAp@}AbAoAdA_AbAw@bAmO|T{Rt[eHbMoAnC_AfCcB~EaBjFcAvDs@`Da@|B]bD]zDYjEUxEeDnr@[vE_@tEi@hEu@bFeAbFaAhEw@tCgAfD{BhGkBbEkDdH{GtNiH`OyLjVcC|GqCdIkCpI}CfKaB`GyA~FcBjH_BhIgA~GoAzIkAjJy@`Hu@fIm@hH]~F]|GWjIOhHIdHEtH?Z"
}
}
]
}
```
#### **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`.
* `geometry` (string, optional): The format of the `geometry` in the response. Valid values are `linestring`, `polyline5` and `polyline6`. `linestring` returns a GeoJSON `LineString`, `polyline5` returns a polyline with 5 decimal places of precision (compatible with other mapping providers) and `polyline6` returns a polyline with 6 decimal places of precision. Defaults to none if not provided.
* `departureTime` (string, optional): The date and time of the route provided as an ISO 8601 date string (e.g., `2025-01-01T14:30:00Z`) which will be used for historical traffic times. If not provided, the current date and time will be used.
**Authentication level**
Publishable
**Default rate limit**
10 requests per second (contact your customer success manager to increase rate limit)
**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**
```json theme={null}
{
"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](http://geojson.org/) 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](/geofencing/trips) has been started, the user's current trip. Present when the trip has a `status` of `started`, `approaching`, or `arrived`.
* `place` (dictionary): When [Places](/geofencing/places) is enabled, the user's current place.
* `country` (dictionary): When [Regions](/geofencing/regions) is enabled, the user's current country.
* `state` (dictionary): When [Regions](/geofencing/regions) is enabled, the user's current state. US-only.
* `dma` (dictionary): When [Regions](/geofencing/regions) is enabled, the user's current DMA (market area). US-only.
* `postalCode` (dictionary): When [Regions](/geofencing/regions) is enabled, the user's current postal code. US-only.
* `beacons` (array): When [Beacons](/geofencing/beacons) have been created, an array of the user's current beacons.
* `fraud` (object): When [Fraud](/geofencing/fraud) is enabled, indicates whether the user passed fraud checks.
**Sample object**
```json theme={null}
{
"_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](/api#track) endpoint.
On iOS and Android, use the [SDK](/sdk/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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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](#route-distance) 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](/geofencing/trips#trip-events) 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](/integrations/olo#order-firing), 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](/integrations/olo), 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](#users) for which the trip is being tracked.
* `userId` (string): The external ID of the [user](#users) for which the trip is being tracked.
* `locations` (array): The location updates tracked while the trip was active. An array of `Point`s in [GeoJSON](http://geojson.org/) 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**
```json theme={null}
{
"_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/route" \
-H "Authorization: prj_live_sk_..."
```
**Authentication level**
Secret
**Sample response**
```json theme={null}
{
"distance": {
"value": 1077.1173573024,
"text": "0.2 mi"
},
"geometry": {
"polyline": "waczjAhnokgEia@BcXXga@Ri|@KmIDsIDyD@mD@"
}
}
```
#### **List trips**
**Definition**
Lists trips. Trips are sorted descending by `updatedAt`.
**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) Retrieves trips by unique IDs. A string, comma-separated including one or more IDs.
* `userId` (string, optional): The Radar `_id` of the [user](https://docs.radar.com/api#users) 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.
* `sortBy` (string, optional): Sorts trips by the specified field in descending order. A string, one of `createdAt` or `updatedAt`. Defaults to `updatedAt`.
* `delayed` (boolean, optional): Retrieves trips that matches specified delayed state.
* `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&externalId=123,456,789" \
-H "Authorization: prj_live_sk_..."
```
**Authentication level**
Secret
**Sample response**
```json theme={null}
{
"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",
"endedAt": "2020-08-20T10:30:55.837Z"
...
},
...
]
}
```
#### **Create a new trip**
Use the [SDK](/sdk/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](/sdk/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](#users) for which the trip is being tracked.
* `mode` (string, optional): The [travel mode](#route-distance) 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](/geofencing/trips#trip-events) 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](/integrations/olo#order-firing), 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" \
-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**
```json theme={null}
{
"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](https://docs.radar.com/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](#route-distance) 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](/geofencing/trips#trip-events) 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](/integrations/olo#order-firing), 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**
```json theme={null}
{
"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**
```json theme={null}
{
"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](http://geojson.org/) 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](http://geojson.org/) 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](#route-distance) for type `isochrone`.
* `metadata` (dictionary): An optional set of custom key-value pairs for the geofence.
* `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. **Deprecated.**
* `userIds` (string, optional): An optional user restriction for the geofence. A string of comma-separated user IDs. If set, the geofence will only generate events for the specified users. 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](/geofencing/trips#trip-events) 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](/geofencing/geofences#operating-hours). 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**
```json theme={null}
{
"_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`.
* `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`.
**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**
```json theme={null}
{
"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. **Deprecated.**
* `userIds` (string, optional): An optional user restriction for the geofence. A string of comma-separated user IDs. If set, the geofence will only generate events for the specified users. 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](/geofencing/geofences#stop-detection) setting for the geofence. Overrides the project-level stop detection setting.
* `mode` (string, required for type `isochrone`): The [travel mode](#routing) for type `isochrone`.
* `tripApproachingThreshold` (number, optional): The [trip approaching threshold](/geofencing/trips#trip-events) 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](/geofencing/places#place-matching), an optional `id` of the Radar [place](/geofencing/places) 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](/geofencing/geofences#operating-hours). 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**
```json theme={null}
{
"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**[**#**](#definition-13)
**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**
```json theme={null}
{
"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**
```json theme={null}
{
"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](/geofencing/places) and [Regions](/geofencing/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](http://geojson.org/) 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**
```json theme={null}
{
"_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](#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](/sdk/sdk) to track users.
#### **Log a conversion**
Conversions are available on the [**Enterprise plan**](https://radar.com/pricing).
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**
```json theme={null}
{
"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**
```json theme={null}
{
"_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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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](/geofencing/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**
```json theme={null}
{
"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**
```json theme={null}
{
"meta": {
"code": 200
},
"chainMetadata": {
"mcdonalds": {
"availableDeals": false
}
},
"chainMappings": {
"mcdonalds": "retailer1"
},
"placeFilters": {
"chain": [
"mcdonalds"
]
}
}
```