Geocoding

Introduction to UNL Geocoding#

Geocoding is the transformation of an address, or free test input, into a concrete location. The UNL geocoder supports simple address lookup, and descriptive landmark based queries.

Simple query:

Kattenburgerstraat 5 027E, 3rd floor, 1018 JA Amsterdam

This is a simple query that searches for the UNL office in Amsterdam

Landmark based query:

Alby cell rt 05/06 jl cilincing bhakti 7 dekat sdn 09 14110 Indonesia

In some areas user may search in a descriptive format, this is difficult for traditional geocoding services to handle. The UNL geocoder is able to parse and extract reference landmarks to find a location.

The following geocoding functionality can be accessed using an API key associated with your service account.

  • UNL Geocoding service allows you to run geocoding process on a single address or a batch of addresses using two separate endpoints described in the next section.

Geocode a single address#

POST https://api.unl.global/v1/geocode#

For a standard address, it takes about 100-200ms, however for a descriptive address , it may take 750ms. Therefore we recommends a rate limit of 80 request per minutes, with a limit of 50,000 requests in a day.

To geocode a large number of addresses, the bulk endpoint should be used.

Query params:

  • address: input query, either a simple or descriptive query

Headers:

  • accept: application/json
  • x-unl-project-id: ID of the VPM
  • x-unl-api-key: API key of the service account

Response Examples:#

{
"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 "
}
}
]
}

Bulk geocode#

The bulk geocoding API allows processing of batch of addresses by submitting a CSV file to the Upload Address endpoint. The process is divided into 3 steps and each step is defined as a separate endpoint.

  1. Step 1 : Upload Address Data
  2. Step 2 : Get Job Status
  3. Step 3: Download geocoded file once job is complete

We recommend a batch size of 1000 request per bulk geocode request.

Step 1 : Upload Address Data#

Bulk geocode jobs can be submitted by uploading a csv file. This file should have a single column "address".

Example.csv

address
"Kattenburgerstraat 5 027E, 3rd floor, 1018 JA Amsterdam"

POST https://api.unl.global/v1/geocode/bulk#

Headers:

  • x-unl-project-id: ID of the VPM
  • x-unl-api-key: API key of the service account

Form data:

  • file: csv file

Response#

{
"jobId": "uuid to track job status"
}

Step 2 - Get job status#

Fetch the status of the submitted job. Once the job is complete, the payload object will contain a link to download the results.

Endpoint: https://api.unl.global/v1/geocode/bulk/:jobId

Headers:

  • x-unl-project-id: ID of the VPM
  • x-unl-api-key: API key of the service account

Response:

{
"jobId": "string",
"jobType": "string",
"projectId": "string",
"startedBy": "string",
"updatedAt": "2022-02-03T21:52:54.340Z",
"jobStatus": "string",
"statusMessage": "string",
"totalTasks": 0,
"completedTasks": 0,
"failedTasks": 0,
"payload": {}
}

Step 3 - download the result file#

Endpoint: https://api.unl.global/v1/download

Query params:

  • token: file download token obtained from the job status payload. The token should be URL encoded.

Result file format

address,coordinates
"Kattenburgerstraat 5 027E, 3rd floor, 1018 JA Amsterdam","{""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""}}]}"

Geocoding Response Parameters#

Geometry#

The geometry property will have type Point, and a coordinates array in the format longituge,latitude as per the geojson standard.

Properties#

The properties field will contain details of the matched result.

address_components#

Contains details of the matched place.

  • place
    • Object containing label and id fields, this represents the the final matched location for the input query.
  • admin
    • object containing details of matched administrative areas. Each field is optional and may contain a null value.
      • street and house_number, may contain a street name and house number if included in the match result, otherwise null.
      • landmark, If the query includes a landmark reference, this array will contain place objects for each landmark that contributed to the result.
"address_components":{
"place": {
"label": "",
"id": ""
},
"street":"",
"admin":{
"city": "",
"district": "",
"sub-district": "",
"county": "",
"state": "",
"country":"",
"postal_code":"",
},
"house_number":"",
"landmark":[{
"label":"",
"id":""
}]
}

unl_location#

The matched location on the unl grid system, type specifies Cell or Cluster.

  • Cell indicates a single cell match, this is equivalent to a geojson Point

  • Cluster indicates a set of cells, this represents a set of cells. This can be considered equivalent to the face of a geojson polygon.

    The locations can be converted to coordinates using the unl core library.

"unl_location": {
"type": "Cell | Cluster",
"id": ""
}

quality_metrics#

Describes the relative quality of the match.

match_type

  • exact: exact match

  • fuzzy: no exact match found, label matched based on best edit distance

  • interpolated: the match location is not precisely known, inferred based on surrounding locations e.g. house number 42 may be interpolated as being between 41 and 43.

  • landmark: match was determined based on its relationship to a specified landmark

  • fallback: match was determined based on its relationship to a admin

accuracy

  • Point: precise location matched
  • Centroid: best location found is within a polygon (e.g. postal code or other admin region). Centroid refers to the center point of this polygon.

match_component

  • Specifies which component of the input query determined the final result house_number | street | landmark

API Response Code

200 : HTTP ok - Request was successfully processed 201 : HTTP created - Bulk job successfully created 401 : HTTP unauthorized - User does not have permission to carry out this action

Edit this page