POST and PUT request body parameters may be sent as application/json or application/x-www-form-urlencoded.
Authentication
All requests must be authenticated. Authenticate using your API keys, found on the Settings page. Include your API key in theAuthorization header.
API endpoints with authentication level Publishable are safe to call client-side (e.g., from the SDK). You should use your publishable API keys to call these endpoints. Use your Test Publishable key for testing and non-production environments. Use your Live Publishable key for production environments.
API endpoints with authentication level Secret are only safe to call server-side. You should use your secret API keys to call these endpoints. Use your Test Secret key for testing and non-production environments. Use your Live Secret key for production environments. Include your API key in the Authorization header.
Sample request
Errors
The API uses standard HTTP response codes. Response codes200: Success202: Accepted400: 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 found409: Conflict429: Too many requests (rate limit exceeded, no state change, or selective throttling)451: Unavailable for legal reasons (country blocklisted)500: Internal server error503: Service temporarily unavailable
Building blocks
Use these endpoints as building blocks for location-based products and services like delivery tracking, store locators, address autocomplete, location-based content and notifications, and more.Track
Tracks a location update. Returns the user and the events generated, depending on project settings. On iOS and Android, use the SDK to track user locations in the foreground or in the background.deviceId is used to identify logged out users. userId and deviceId are used to identify logged in users. If a matching user already exists, it will be updated. If not, a new user will be created.
Do not send any PII, like names, email addresses, or publicly available IDs, for userId. See privacy best practices for more information.
This endpoint is stateful. For anonymous or stateless context, call the context endpoint instead.
Definition
POST https://api.radar.io/v1/track
Body parameters
deviceId(string, required): A device ID for the user. Used to identify logged out users.userId(string, optional): A stable unique ID for the user. Used withdeviceIdto identify logged in users. Not required for logged out users.latitude(number, required): The user’s current latitude. A number between -90 and 90.longitude(number, required): The user’s current longitude. A number between -180 and 180.accuracy(number, required): The accuracy of the user’s current latitude and longitude, in meters. A number greater than 0. Used when evaluating the confidence of geofence events.foreground(boolean, optional):trueif the client is in the foreground,falseif the client is in the background.stopped(boolean, optional):trueif the user is stopped,falseif 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 ofiOS,Android, orWeb.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):trueif the location is replayed,falseif the location is not replayed. Defaults tofalse.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.
Context
Gets context for a location, depending on project settings. This endpoint is anonymous by default and stateless. For stateful context, call the track endpoint instead. DefinitionsGET https://api.radar.io/v1/context
Query parameters
coordinates(string, required): The coordinates. A string in the formatlatitude,longitude.userId(string, optional): A stable unique ID for the user. Required for MTU-based pricing.
Geocoding
Forward geocode
Geocodes an address, converting address to coordinates. This endpoint is best for complete addresses. For partial addresses or place names, call the autocomplete endpoint instead. Returns a confidence level, as defined below:exact: The result matches the query sent.interpolated: A result where there is a record for the street but not the exact building number, so the value is calculated between two known building numbers.fallback: A result where Radar does not have a matching record and cannot interpolate the results. Radar falls back to the region containing the query.
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 ofplace,address,postalCode,locality,county,state,country,coarse, andfine. Note thatcoarseincludes all ofpostalCode,locality,county,state, andcountry, whereasfineincludesaddressandplace. If not provided, results fromaddressandcoarselayers will be returned.country(string, optional): An optional countries filter. A string of comma-separated countries, the unique 2-letter country code.lang(string, optional): Specifies the language for the results. A string, one ofar,de,en,es,fr,ja,ko,pt,ru,zh. Defaults toen.
Reverse geocode
Reverse geocodes a location, converting coordinates to address. DefinitionsGET https://api.radar.io/v1/geocode/reverse
Query parameters
coordinates(string, required): The coordinates to reverse geocode. A string in the formatlatitude,longitude.layers(string, optional): Optional layer filters. A string, comma-separated, including one or more ofplace,address,postalCode,locality,county,state,country,coarse, andfine. Note thatcoarseincludes all ofpostalCode,locality,county,state, andcountry, whereasfineincludesaddressandplace. If not provided, results fromaddressandcoarselayers will be returned.
IP geocode
Geocodes the requester’s IP, converting IP address to city, state, and country. DefinitionsGET https://api.radar.io/v1/geocode/ip
Authentication level
Publishable
Default rate limit
10 requests per second per device
Sample request
Search
Autocomplete
Autocompletes partial addresses and place names, sorted by relevance and proximity. DefinitionsGET 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 formatlatitude,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 ofplace,address,postalCode,locality,county,state,country,coarse, andfine. Note thatcoarseincludes all ofpostalCode,locality,county,state, andcountry, whereasfineincludesaddressandplace. If not provided, results fromaddressandcoarselayers 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.lang(string, optional): Specifies the language for the results. A string, one ofar,de,en,es,fr,ja,ko,pt,ru,zh. Defaults toen.
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
Search users
Searches for users near a location, sorted by distance. DefinitionsGET https://api.radar.io/v1/search/users
Query parameters
near(string, required): A location for the search. A string in the formatlatitude,longitude.radius(number, optional): The radius to search, in meters. A number between 100 and 10000. Defaults to 1000. Ifmodeis specified, theradiusis the travel duration in minutes.mode(string, optional): The travel mode. A string, one ofcar,truck,foot, orbike.metadata[key](string, optional): Optional metadata filters. Values may be of type string. Type will be automatically inferred. For example, to match onworking == true, use&metadata[working]=true.limit(number, optional): The max number of users to return. A number between 1 and 100. Defaults to 10.
Search geofences
Searches for geofences near a location, sorted by distance. DefinitionsGET https://api.radar.io/v1/search/geofences
Query parameters
near(string, required): A location for the search. A string in the formatlatitude,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 onoffers == true, use&metadata[offers]=true.includeGeometry(boolean, optional): Include geofence geometries in the response. Defaults totrue.
includeGeometries must be set to false.
Authentication level
Publishable
Default rate limit
100 requests per second
Sample request
Search places
Searches for places near a location, sorted by distance. DefinitionsGET https://api.radar.io/v1/search/places
Query parameters
chains(string, optional): Chain slug filters. A string, comma-separated. If your project has a chain mapping, the mapped ID can be used in place of the chain slug. If not provided,categoriesmust be provided.categories(string, optional): Category filters. A string, comma-separated. If not provided,chainsmust be provided.iataCode(string, optional): The 3-letter IATA code for the airport to search. If provided, no other parameters are required.chainMetadata[key](optional): Optional chain metadata filters. Values may be of type string, boolean, or number. Type will be automatically inferred. For example, to match onoffers == true, use&chainMetadata[offers]=true.near(string, required): A location for the search. A string in the formatlatitude,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.
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 endpoint instead. Returns averificationStatus 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.
recordType value in the metadata field as part of the result, values are defined below according to USPS standards:
S: Street AddressP: Post Office BoxR: Rural RouteH: High-riseF: FirmG: General Delivery
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.
GET https://api.radar.io/v1/addresses/validate
Query parameters
city(string, required): The city name.stateCode(string, required): The 2-letter state abbreviation (e.g.,NY).postalCode(string, required): The postal or zip code. Plus 4 codes are accepted but not required.countryCode(string, required): The unique 2-letter country code (e.g.,US).number(string, optional): The building or P.O. box number. If not provided,addressLabelmust be provided.street(string, optional): The street name. If not provided,addressLabelmust 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,numberandstreetmust be provided.
Routing
Distance
Calculates the travel distance and duration between an origin and a destination. DefinitionsGET https://api.radar.io/v1/route/distance
Query parameters
origin(string, required): The origin. A string in the formatlatitude,longitude.destination(string, required): The destination. A string in the formatlatitude,longitude.modes(string, required): The travel modes. A string, comma-separated, including one or more ofcar,truck,foot, orbike.units(string, optional): The distance units. A string,metricorimperial. Defaults toimperialif not provided. In the response,distance.valuewill be in meters formetricand in feet forimperial.avoid(string, optional): The features that calculated routes should avoid. A string, comma-separated, including one or more oftolls,highways,ferriesandborderCrossings. No features are avoided if not provided.geometry(string, optional): The format of thegeometryin the response. Valid values arelinestring,polyline5andpolyline6.linestringreturns a GeoJSONLineString,polyline5returns a polyline with 5 decimal places of precision (compatible with other mapping providers) andpolyline6returns 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.
Matrix
Calculates the travel distances and durations between multiple origins and destinations for up to 625 routes. DefinitionsGET https://api.radar.io/v1/route/matrix
Query parameters
origins(string, required): A list of origins. A pipe-delimited string in the formatlatitude0,longitude0|latitude1,longitude1|....destinations(string, required): A list of destinations. A pipe-delimited string in the formatlatitude0,longitude0|latitude1,longitude1|....mode(string, required): The travel mode. A string, one ofcar,truck,foot, orbike.units(string, optional): The distance units. A string,metricorimperial. Defaults toimperialif not provided.avoid(string, optional): The features that calculated routes should avoid. A string, comma-separated, including one or more oftolls,highwaysandferries. 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.
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. DefinitionsPOST 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}
- Each object in the list should be of the form
mode(string, optional): The travel mode. A string, one ofcar,truck,foot, orbike. Defaults tocar.roadAttributes(string, optional): Attributes of matched roads to be included in the response. A string, comma-separated, including one or more ofspeedLimit,names, androadClass.roadClassreturn values will be one of:motorwaytrunkprimarysecondarytertiaryunclassifiedresidentialservice_other
units(string, optional): The distance and speed units. A string,metricorimperial. Defaults toimperialif not provided.geometry(string, optional): The format of thegeometryin the response. Valid values arelinestring,polyline5andpolyline6.linestringreturns a GeoJSONLineString,polyline5returns a polyline with 5 decimal places of precision (compatible with other mapping providers) andpolyline6returns a polyline with 6 decimal places of precision. Defaults topolyline6if not provided.
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 connectresidentialroads.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. DefinitionsGET 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 formatlatitude0,longitude0|latitude1,longitude1|....mode(string, optional): The travel mode. A string, one ofcar,truck,foot, orbike. Defaults tocar.units(string, optional): The distance units. A string,metricorimperial. Defaults toimperial.avoid(string, optional): The features that calculated routes should avoid. A string, comma-separated, including one or more oftolls,highways,ferriesandborderCrossings. No features are avoided if not provided.geometry(string, optional): The format of thegeometryin the response. Valid values arelinestring,polyline5andpolyline6.linestringreturns a GeoJSONLineString,polyline5returns a polyline with 5 decimal places of precision (compatible with other mapping providers) andpolyline6returns a polyline with 6 decimal places of precision. Defaults topolyline6if 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.
alternatives(boolean, optional): Specifies whether to try to return alternative routes. This feature is available if only two locations are specified. Defaults tofalse.lang(string, optional): Specifies the language for the results. A string, one ofde,en,es,fr,ja,ko,pt,ru. Defaults toen.
Optimize route
Calculates the optimal ordering and route to visit a list of locations. DefinitionsGET 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 formatlatitude0,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 ofcar,truck,foot, orbike. Defaults tocar.units(string, optional): The distance units. A string,metricorimperial. Defaults toimperial.geometry(string, optional): The format of thegeometryin the response. Valid values arelinestring,polyline5andpolyline6.linestringreturns a GeoJSONLineString,polyline5returns a polyline with 5 decimal places of precision (compatible with other mapping providers) andpolyline6returns 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.
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):trueif the user was created with yourliveAPI key,falseif the user was created with yourtestAPI 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, aPointin GeoJSON format.locationAccuracy(number): The accuracy of the user’s current location in meters.foreground(boolean):trueif the user’s current was updated in the foreground,falseif the user’s current location was updated in the background.stopped(boolean):trueif the user’s current location was updated while stopped,falseif the user’s current location was updated while moving.deviceType(string): The user’s device type, one ofiOS,Android, orWeb.createdAt(datetime): The datetime when the user was created.updatedAt(datetime): The datetime when the user’s location was last updated.geofences(array): An array of the user’s current geofences.trip(dictionary): When a Trip has been started, the user’s current trip. Present when the trip has astatusofstarted,approaching, orarrived.place(dictionary): When Places is enabled, the user’s current place.country(dictionary): When Regions is enabled, the user’s current country.state(dictionary): When Regions is enabled, the user’s current state. US-only.dma(dictionary): When Regions is enabled, the user’s current DMA (market area). US-only.postalCode(dictionary): When Regions is enabled, the user’s current postal code. US-only.beacons(array): When Beacons have been created, an array of the user’s current beacons.fraud(object): When Fraud is enabled, indicates whether the user passed fraud checks.
Create a user
To create a user, call the track endpoint. On iOS and Android, use the SDK to track users.List users
Lists users. Users are sorted descending byupdatedAt.
Definition
GEThttps://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.
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
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
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):trueif the user was created with yourliveAPI key,falseif the user was created with yourtestAPI key.externalId(string): A stable unique ID for the trip. Depending on your use case, may represent an order ID, a delivery ID, or something else.metadata(dictionary): An optional set of custom key-value pairs for the trip, displayed in the trip tracking dashboard.mode(string): The travel mode for the trip. A string, one offoot,bike, andcar.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, includingdurationin minutes anddistancein meters.approachingThreshold(number): For trips with a destination, the trip approaching threshold setting for the trip (in minutes). Overrides the geofence-level and project-level trip approaching threshold settings.createdAt(datetime): The datetime when the trip was started.updatedAt(datetime): The datetime when the trip’s location was last updated.scheduledArrivalAt(datetime): Required for the Olo order firing integration, the backstop datetime when the device on the trip is expected to arrive. The order will be firedapproachingThresholdminutes beforescheduledArrivalAt.orderFiredAt(datetime): From the Olo integration, the datetime when the order associated with the trip was fired.arrivedAt(datetime): For trips with a destination, the datetime when the user arrived at the trip destination (entered the destination geofence).completedAt(datetime): The datetime when the trip was stopped.status(string): The status of the trip, one ofpending,started,approaching,arrived,expired,completed, orcanceled.user(dictionary): The user for which the trip is being tracked.userId(string): The external ID of the user for which the trip is being tracked.locations(array): The location updates tracked while the trip was active. An array ofPoints in GeoJSON format.delay(dictionary): The predicted delay for the trip, including adelayedboolean flag and ascheduledArrivalTimeDelaywith the delay amount in minutes.
Get a trip
Gets a trip. The trip can be referenced by Radar_id or externalId.
Definition
GEThttps://api.radar.io/v1/trips/:idGET
https://api.radar.io/v1/trips/:externalId
Default rate limit
10 requests per second
Sample request
List trips
Definition Lists trips. Trips are sorted descending byupdatedAt.
GEThttps://api.radar.io/v1/trips
Query parameters
status(string, optional): Retrieves trips by status. A string, comma-separated including one or more ofpending,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_idof the user for which the trip is being tracked.includeLocations(boolean, optional): Whether to include locations on trips. Defaults tofalse.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 ofcreatedAtorupdatedAt. Defaults toupdatedAt.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.
Create a new trip
Use the SDK to start trips and track users for most use cases. Trips can also be created server-side or through integrations (e.g., Olo). Location updates with the specifieduserId from the SDK will update the trip for that user.
Definition
Creates a new trip.
POSThttps://api.radar.io/v1/trips
Body parameters
externalId(string, required): A stable unique ID for the trip. Depending on your use case, it may represent an order ID, a delivery ID, or something else.destinationGeofenceTag(string, optional): For trips with a destination, the tag of the destination geofence.destinationGeofenceExternalId(string, optional): For trips with a destination, the external ID of the destination geofence.userId(string, optional): The external ID of the user for which the trip is being tracked.mode(string, optional): The travel mode for the trip. A string, one offoot,bike, andcar. Defaults tocar.approachingThreshold(number, optional): For trips with a destination, the trip approaching threshold setting for the trip (in minutes). Overrides the geofence-level and project-level trip approaching threshold settings.scheduledArrivalAt(datetime): Required for the Olo order firing integration, the backstop datetime when the device on the trip is expected to arrive. The order will be firedapproachingThresholdminutes beforescheduledArrivalAt.metadata(dictionary, optional): An optional set of custom key-value pairs for the trip.
Update a trip
Updates a trip. The trip can be referenced by Radar_id or externalId.
On iOS and Android, use the SDK to update trips.
Definition
PATCHhttps://api.radar.io/v1/trips/:id/updatePATCH
https://api.radar.io/v1/trips/:externalId/update
Body parameters
status(string, required): The new status of the trip, one ofpending,started,approaching,arrived,completed, orcanceled.mode(string, optional): The travel mode for the trip. A string, one offoot,bike, andcar.destinationGeofenceTag(string, optional): For trips with a destination, the tag of the destination geofence.destinationGeofenceExternalId(string, optional): For trips with a destination, the external ID of the destination geofence.approachingThreshold(number, optional): For trips with a destination, the trip approaching threshold setting for the trip (in minutes). Overrides the geofence-level and project-level trip approaching threshold settings.scheduledArrivalAt(datetime, optional): Required for the Olo order firing integration, the backstop datetime when the device on the trip is expected to arrive. The order will be firedapproachingThresholdminutes beforescheduledArrivalAt.metadata(dictionary, optional): An optional set of custom key-value pairs for the trip.
Delete a trip
Deletes a trip. The trip can be referenced by Radar_id or externalId.
Definition
DELETEhttps://api.radar.io/v1/trips/:id
Default rate limit
10 requests per second
Authentication level
Secret
Sample request
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):trueif the geofence was created with yourliveAPI key,falseif the user was created with yourtestAPI 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 ofcircle,polygon, orisochrone.geometry(polygon): The geometry of the geofence. Coordinates for typepolygon. A calculated polygon approximation for typecircleandisochrone. APolygonin GeoJSON format.geometryCenter(point): The center for typecircle. The calculated centroid of the polygon for typepolygon. The destination for typeisochrone. APointin GeoJSON format.geometryRadius(number): The radius in meters for typecircle. The calculated approximate radius of the polygon for typepolygon. The travel duration in minutes for typeisochrone.mode(string): The travel mode for typeisochrone.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 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 anduser.dwelled_in_geofenceis enabled in settings, an event is triggered when a user dwells in the geofence longer than the threshold (in minutes).enabled(boolean): Iftrue, the geofence will generate events. Iffalse, the geofence will not generate events. Defaults totrue.operatingHours(dictionary): An optional set of key-value pairs restricting the operating hours of the geofence. Each key is a day of the week, and each value is a list of pairs, where a pair indicates one opening and closing time for that day inHH:mmformat.
List geofences
Definition Lists geofences. Geofences are sorted descending byupdatedAt.
GEThttps://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 specifiedtag.externalId(string, optional): Retrieves geofences with the specifiedexternalId.metadata[key](string, optional): Optional metadata filters. Values may be of type string. Type will be automatically inferred. For example, to match onoffers == true, use&metadata[offers]=true.
Get a geofence
Gets a geofence. The geofence can be uniquely referenced by Radar_id or by tag and externalId.
Definition
GEThttps://api.radar.io/v1/geofences/:idGET
https://api.radar.io/v1/geofences/:tag/:externalId
Default rate limit
10 requests per second
Authentication level
Secret
Sample request
Upsert a geofence
Upserts a geofence. The geofence can be uniquely referenced bytag 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
PUThttps://api.radar.io/v1/geofences/:tag/:externalIdPUT
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 ofcircle,polygon, orisochrone.coordinates(array, required ifaddressandplaceIdare not included): An array or JSON string representing a center for typecircleor a destination for typeisochronein 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 typepolygon. Note that longitude comes before latitude, a GeoJSON convention.address(string, required ifcoordinatesandplaceIdare not included): An address to search for, and if found, will represent the center for typecircleorisochrone. Ifaddressandcoordinatesare both provided, they must be nearby, andcoordinateswill take precedent. Ignored for typepolygon.radius(number, required for typecircleandisochrone): The radius in meters for typecircle, a number between10and10000. The travel duration in minutes for typeisochrone. Ignored for typepolygon.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): Iftrue, the geofence will generate events. Iffalse, the geofence will not generate events. Defaults totrue.disableAfter(datetime, optional): Use to create temporary geofences. If set, the geofence will be disabled after the specified datetime. A date or valid ISO date string.deleteAfter(datetime, optional): Use to create temporary geofences. If set, the geofence will be deleted after the specified datetime. A date or valid ISO date string.stopDetection(boolean, optional): The stop detection setting for the geofence. Overrides the project-level stop detection setting.mode(string, required for typeisochrone): The travel mode for typeisochrone.tripApproachingThreshold(number, optional): The trip approaching threshold setting for the geofence (in minutes). Overrides the project-level trip approaching threshold setting.dwellThreshold(number, optional): An optional field to trigger dwell events. If set anduser.dwelled_in_geofenceis enabled in settings, an event is triggered when a user dwells in the geofence longer than the threshold (in minutes).placeId(string, required ifcoordinatesandaddressare not included): For place matching, an optionalidof the Radar place to match to the geofence. If provided and found, the place centroid will overridecoordinatesandaddress.operatingHours(dictionary, optional): An optional set of key-value pairs restricting the operating hours of the geofence. Each key is a day of the week (e.g.,Sunday) or the three letter abbreviation of the day (e.g.,Sun), case insensitive. Each value is a list of pairs, where a pair indicates one opening and closing time for that day. For example, a restaurant only open for lunch and dinner on Sundays would be{ Sunday: [["11:00", "14:00"], ["19:00", "22:00"]] }. Accepted time formats includeh:mm aa(e.g.,12:45 AM) andHH:mm(e.g.,00:45). If not set, the geofence will always be open.
Delete a geofence
Deletes a geofence. The geofence can be uniquely referenced by Radar_id or by tag and externalId.
Definition#
DELETEhttps://api.radar.io/v1/geofences/:idDELETE
https://api.radar.io/v1/geofences/:tag/:externalId
Default rate limit
10 requests per second
Authentication level
Secret
Sample request
Get users in a geofence
Gets users currently in a geofence. Definition GEThttps://api.radar.io/v1/geofences/:tag/:externalId/users
Default rate limit
10 requests per second
Authentication level
Secret
Sample request
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 andcreatedAt.live(boolean):trueif the event was generated for a user and geofence created with yourliveAPI key,falseif the event was generated for a user and geofence created with yourtestAPI key.type(string): The type of event. By default, events are generated when a user enters a geofence (typeuser.entered_geofence) or exits a geofence (typeuser.exited_geofence). Places and Regions also generate events.user(dictionary): The user for which the event was generated.geofence(dictionary): Foruser.entered_geofenceanduser.exited_geofenceevents, the geofence for which the event was generated, includingdescription,tag, andexternalId.place(dictionary): Foruser.entered_placeanduser.exited_placeevents, the place for which the event was generated, includingname,categories,chain, andfacebookId.alternatePlaces(array): Foruser.entered_placeevents, alternate place candidates.verifiedPlace(dictionary): For verifieduser.entered_placeevents, the verified place.location(point): The location of the user at the time of the event, aPointin GeoJSON format.locationAccuracy(number): The accuracy of the user’s location at the time of the event in meters.confidence(number): The confidence level of the event, one of3(high),2(medium), or1(low).duration(number): On exit events, the duration between entry and exit events, in minutes.
Generate an entry or exit event
To generate an entry or exit event, call the track endpoint to trigger an event. For example, specify alatitude and longitude to enter a geofence that you have created.
On iOS and Android, use the SDK to track users.
Log a conversion
Conversions are available on the Enterprise plan.
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.
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):trueif the beacon was created with yourliveAPI key,falseif the beacon was created with yourtestAPI 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 ofibeacon(supported on iOS and Android) oreddystone(supported on Android only).uuid(string, required foribeacon): For iBeacons, the UUID of the beacon.major(string, required foribeacon): For iBeacons, the major ID of the beacon.minor(string, required foribeacon): For iBeacons, the minor ID of the beacon.uid(string, required foreddystone): For Eddystone beacons, the UID of the beacon.instance(string, required foreddystone): 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 typepointin[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.
List beacons
Lists beacons. Beacons are sorted descending bycreatedAt.
Definition
GEThttps://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 specifiedtag.externalId(string, optional): Retrieves beacons with the specifiedexternalId.
Get a beacon
Gets a beacon. The beacon can be uniquely referenced by Radar_id or by tag and externalId.
Definition
GEThttps://api.radar.io/v1/beacons/:idGET
https://api.radar.io/v1/beacons/:tag/:externalId
Default rate limit
10 requests per second
Authentication level
Secret
Sample request
Create a beacon
Creates a beacon. Definition POSThttps://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 ofibeacon(supported on iOS and Android) oreddystone(supported on Android only).uuid(string, required foribeacon): For iBeacons, the UUID of the beacon.major(string, required foribeacon): For iBeacons, the major ID of the beacon.minor(string, required foribeacon): For iBeacons, the minor ID of the beacon.uid(string, required foreddystone): For Eddystone beacons, the UID of the beacon.instance(string, required foreddystone): 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.
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
PUThttps://api.radar.io/v1/beacons/:idPUT
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 ofibeacon(supported on iOS and Android) oreddystone(supported on Android only).uuid(string, required foribeacon): For iBeacons, the UUID of the beacon.major(string, required foribeacon): For iBeacons, the major ID of the beacon.minor(string, required foribeacon): For iBeacons, the minor ID of the beacon.uid(string, required foreddystone): For Eddystone beacons, the UID of the beacon.instance(string, required foreddystone): 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): Iftrue, the beacon will generate events. Iffalse, the beacon will not generate events. Defaults totrue.
Delete a beacon
Deletes a beacon. The beacon can be uniquely referenced by Radar_id or by tag and externalId.
Definition
DELETEhttps://api.radar.io/v1/beacons/:idDELETE
https://api.radar.io/v1/beacons/:tag/:externalId
Default rate limit
10 requests per second
Authentication level
Secret
Sample request
Manage your Radar project settings
Places settings
Places settings represents your current project settings for Places. Object fieldschainMetadata(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 GEThttps://api.radar.io/v1/settings
Default rate limit
10 requests per second
Authentication level
Secret
Sample request
Update Places settings
Updates your Places settings. Definition PATCHhttps://api.radar.io/v1/settings
Default rate limit
10 requests per second
Authentication level
Secret
Sample request