Custom Places API¶

Sygic Authentication API - quick overview¶

To be able to upload your Custom Places, you need an authentication token from our Auth API. To obtain one, you need your clientID that was provided to you. Custom places are uploaded by a specific clientId on behalf of your application's clientId.

The url which you will be POST-ing is https://auth.sygic.com/oauth2/token

The body of your request would look like this:

{
    "client_id": "your_client_id",
    "grant_type": "client_credentials" // do not change this
}

An access token will be returned in the response, you will need it for the actual Custom Places API calls.

Pre-requisites¶

To ensure security, we will provide you with a new clientID which is different from the one that you use in the app. This clientIdD will be used only for uploading Custom Places and will not be used in your app. You need to call the Authentication API with this one. Then in the request body itself it will be necessary to add your app's clientId "on_behalf_of": "your-app-client-id". This will ensure that the places are uploaded for your app."

Custom Places Integrator API¶

Here we will look at the integrator's part of the Custom Places API. You can find the swagger here. Make sure to choose the "Integrator v2" version in the right top corner.

Tip

The swagger also contains schemas for how the JSON should look for Place and Category objects.

Uploading places¶

To upload places, you will have to call a PUT request https://places.api.sygic.com/v2/api/integrator/places with the following:

Authorization header with the value Bearer <your_access_token> that you received from the Authentication API
Content-Type header with the value application/json
body with the JSON of your places

Note

If a new unique id is provided, the place is added. If the id already exists, the place is updated.

Deleting places¶

To delete places, call a DELETE request https://places.api.sygic.com/v2/api/integrator/places with the following:

Authorization header with the value Bearer <your_access_token> that you received from the Authentication API
body with the JSON containig IDs of places you want to delete along with the "on_behalf_of" key

For example:

{
    "ids": [
        "00000000-0000-0000-0000-000020e90002", "00000000-0000-0000-0000-000020e90003"
    ],
    "on_behalf_of": "your-app-client-id"
}

Adding Custom Place categories¶

Adding custom place categories is done in a similar way as adding places. You will have to call a POST request to https://places.api.sygic.com/v2/api/integrator/categories with following parameters:

Authorization header with the value Bearer <your_access_token> that you received from the Authentication API
Content-Type header with the value application/json
body with the JSON of your categories and "on_behalf_of" key

Dumping places and Place categories¶

As an integrator you can also request a dump of all places or categories that are currently in the database.

To retrieve all places, call a GET request https://places.api.sygic.com/v2/api/integrator/places with "datasets" and "on_behalf_of" parameters
To retrieve all place categories, call a GET request https://places.api.sygic.com/v2/api/integrator/categories with "datasets" and "on_behalf_of" parameters

Note

Both of the requests only require the Authorization header with the value Bearer <your_access_token> that you received from the Authentication API. If you are using datasets, add a parameter datasets which is a array of datasets separated by | sign to filter results. Also, it is possible that the response will be too large to be sent in one batch. In that case it will be split into multiple batches and contain "prev_page" and "next_page" keys and you will have to call the same request again with the "page_token" parameter.