Places API

Getting Started

The Localytics Places POI Sync API lets customers send a full set of geofences to Localytics for use in Localytics Places. POIs sent to this endpoint in bulk are inserted if new, and updated if existing, and all geofences not in the payload are deactivated.

A subscription to Places is required to use this feature; if you don't have access, reach out to your Account Manager or contact us here.

Implementation Details

Before integrating, here are some details you need to know:

• POI updates are typically available to be downloaded by the related mobile app within five minutes.
• Places Campaigns and POI are synced to devices on a daily cadence to devices in the background on significant location updates, or on session start.
• POI synced to this API may take hours or days to fully propagate to devices, particularly if the devices haven't had a significant location change.
• Each app can have up to 10,000 active POI at a time.
• Any geofences that are active for your app but are not part of your request to the Sync API will be deactivated.
• Event data for deactivated geofences is still retained for analytics and historical behavioral targeting.

POI Sync Transactions

Endpoint

The URL for POI sync requests is:

https://api.localytics.com/v1/places/apps/[app_id]/geofence_sync

Authentication

Places POI Sync uses Basic Access Authentication. You can use your organization’s API Key/Secret to authenticate the request. These are the same credentials you use to authenticate requests to the Localytics Profile API, Push API, and Events API.

Authorization

Places POI Sync requires a subscription to the Places product, and the app ID in the URL must belong to the same organization as your API key/secret.

You can find your organization’s API Key/Secret by navigating to the API Keys section of the Account page in the Localytics Dashboard.

Rate Limits

Places POI Sync enforces the following rate limit per app:

• 20 requests per hour.
• 50 requests per day.

Request Structure

Required Headers

• Content-Type: application/json

Request Body Format

Pass an active_geofences array including all geofences you want to create or activate. Other existing geofences will be deactivated.

{
"active_geofences": [
  { "identifier": "headquarters", "description": "The HQ", "latitude": 45.000,
    "longitude": 45.000, "radius": 9000, "labels": ["boston"] }
]
}

Individual geofence structure

New geofences will be created; existing geofences will be activated (if inactive) and have any passed field values replaced with the ones you specify.

{
"identifier": string,    // required, cannot contain apostrophe
"description": string,   // optional, falls back to existing value, defaults to NULL
"latitude": number,      // optional, falls back to existing value, number, error if not provided and no existing value
"longitude": number,     // optional, falls back to existing value, error if not provided and no existing value
"radius": number,        // optional, falls back to existing value, error if not provided and no existing value
"send_enter": boolean,   // optional, falls back to existing value, defaults to true
"send_exit": boolean,    // optional, falls back to existing value, defaults to true
"labels": array[string], // optional, falls back to existing value, defaults to []
"attributes": object[string, string] // optional, falls back to existing value, defaults to {}
}

Deactivating All Geofences

Pass an empty active_geofences array to deactivate all geofences.

{
"active_geofences": []
}

Reactivating Inactive Geoences

If an inactive geofence already exists on the backend, passing the identifier alone is enough to activate it. This request reactivates an existing "headquarters" geofence and deactivates other geofences:

{
"active_geofences": [
  { "identifier": "headquarters" }
]
}

Editing a Single Field on an Existing Place

Any fields on an existing geofence that are not explicitly passed an updated value will be left as-is. For example, this request would modify an existing "headquarters" geofence with a new radius, but leave latitude, longitude, etc. unmodified, and deactivate geofences other than "headquarters."

{
"active_geofences": [
 { "identifier": "headquarters", "radius": 5000 }
]
}

Errors

Errors indicate which of your active_geofences failed validation. For example, the following request includes a Place with an invalid radius and a Place with an invalid latitude:

{
"active_geofences": [
  {"identifier": "headquarters"},
  {"identifier": "other_identifier", "latitude": 45.000, "longitude": 45.000,
"radius": -50 },
  {"identifier": "yet_another", "latitude": 5000, "longitude": 90, "radius": 500
}
] }

The above request would lead to an error response with an HTTP 422 response and a body of:

{
"error": {
  "1": [
    "Radius must be greater than or equal to 0"
], "2": [
    "Latitude must be less than or equal to 90"
  ]
} }