Accessing the API

Access to the UNL API is managed via service accounts and api-keys. A service account is a special type of account intended to represent a non-human user that needs to access data in a VPM

Create a service account and api key#

Select the Service Accounts option from the left side menu or visit https://studio.unl.global/serviceAccounts and click on Create New Service Account to create & name your service account.

To genereate an API key, select Create New Api Key from the service account's page. You can copy & manage API keys from a service account's settings page.

Connect Project to Service Account#

The next step is to connect the service account to your Virtual private map. Click on the [...] to select VPM settings from the VPM list page. On the VPM settings page, add your service account by clicking on Add service account.

Add Contributor Rights#

The last step is to give the service account contributor rights in order to allow adding data to the project. From the VPM settings page, open the dropdown from the ROLE column correspoding to your service account and select Can Contribute.

Making an api request#

Now that a VPM, service account, and api are configured it is possible to make requests to the UNL API. Below is an example forward geocode request.

Headers:

  • x-unl-api-key: The api key associated with your service account.
  • x-project-id: The VPM id that your service account has access to.

Query params:

  • address: The input geocode query

Request:

curl -X 'GET' \
'https://api.unl.global/v1/geocode?address=Kattenburgerstraat%205%20027E%2C%203rd%20floor%2C%201018%20JA%20Amsterdam' \
-H 'accept: application/json' \
-H 'x-unl-api-key: tEEDumqtGXMHe1nvjyDxINjuTbkU22y2' \
-H 'x-unl-project-id: cf6ffeca-3177-4447-95aa-b9f598b4f3ac'

Response:

{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
4.91628,
52.3718
]
},
"properties": {
"address_components": {
"place": {
"label": "Kattenburgerstraat 5, 1018 JA Amsterdam, Nederland",
"id": "95909077854d852e9e714ea5889bb5c9"
},
"street": "Kattenburgerstraat",
"admin": {
"city": "Amsterdam",
"district": "Amsterdam-Centrum",
"sub_district": null,
"county": "Amsterdam",
"state": "Noord-Holland",
"country": "Nederland",
"postal_code": "1018 JA"
},
"house_number": null,
"landmark": []
},
"quality_metrics": {
"match_type": "exact",
"match_component": "house",
"accuracy": "point",
"score": 1
},
"address_type": "",
"formatted_address": "Kattenburgerstraat 5, 1018 JA Amsterdam, Nederland",
"unl_location": {
"type": "Cell",
"id": "u173zvg"
},
"index": 0,
"query": "Kattenburgerstraat 5 027E, 3rd floor, 1018 JA Amsterdam "
}
}
]
}