Multi Geocoding API

Introduction

NextBillion’s Multi-Geocoding API allows you to find the geo-coordinates, and addresses(Place, Locality, administrative area) of POIs from multiple data sources. It also enables you to easily manage the places’ information to improve the utility of the search results based on custom business needs. For instance,

1. Create custom locations that your business needs

2. Get combined results for a searched text from all data sources i.e default and custom datasets

3. Override the results of default search provider in case of duplicate or similar places and prioritize custom places in search results

Search Place

Use this method to find known places in default or your own custom (proprietary) dataset and get a combined search result. It accepts free-form, partially correct or even incomplete search texts. Results would be ranked based on the search score of a place.

Request Parameters

Request Body

Response Schema

Sample Request

1
curl --location --request POST 'https://api.nextbillion.io/multigeocode/search?key=yourapikey'
2
        --header 'Content-Type: application/json'
3
        --data '{...}'

Sample Response

1
{
2
     "entities": "[...]"
3
}

Batch Geocode

The method enables searching for multiple known places in a single request. Provide up to 100 search queries to get a response with matching places for all provided queries. It accepts any free-form texts or known place names in the request body, to retrieve relevant results. The results are ranked based on the search score of a place.

Request Parameters

Request Body

Response Schema

Sample Request

1

2
curl --location 'https://api.nextbillion.io/h/geocode/batch?key=<your_api_key>' 
3
--header 'Content-Type: application/json' 
4
--data '[...]'

Sample API Response

1
[
2
    {
3
        "items": "[...]"
4
    },
5
    {
6
        "items": "[...]"
7
    },
8
    
9
]

Add A Place

Add place method provides the flexibility to create custom places in a way that suits your business needs. The newly created place and its attributes can be added to custom (proprietary) dataset - to the effect of building your own places dataset (s) - or, to a default dataset. Overcome inaccurate ‘POI’ details from default search provider by creating custom, highly accurate ‘POIs’

Request Parameters

Request Body

Response Schema

Sample Request

1
curl --location --request POST 'https://api.nextbillion.io/multigeocode/place?key=yourapikey'
2
  --header 'Content-Type: application/json'   --data-raw '{...}'

Sample Response

1
{
2
  "docId": "MGA-41e325fd-77ee-475b-b386-9da926774e05"
3
}

Get Place

Use this method to get the details of previously created custom places using its NextBillion ID.

Request Parameters

Response Schema

Sample Request

1
curl --location --request GET 'https://api.nextbillion.io/multigeocode/place/MGA-d87c9011-4b9f-4e99-bd6e-510ae51341a7?key=yourapikey'

Sample Response

1
{
2
  "status": 200,
3
  "msg": "Ok"
4
}

Update Place

Add place method provides the flexibility to create custom places in a way that suits your business needs. The newly created place and its attributes can be added to custom (proprietary) dataset - to the effect of building your own places dataset (s) - or, to a default dataset. Overcome inaccurate ‘POI’ details from default search provider by creating custom, highly accurate ‘POIs’

Request Parameters

Request Body

Response Schema

Sample Request

1
curl --location --request PUT 'https://api.nextbillion.io/multigeocode/place/MGA-110a090c-657b-412d-a490-d3855322ff1b?key=your_api_key' --header 'Content-Type: application/json' --data '{...}'

Sample Response

1
{
2
    "docId": "MGA-d87c9011-4b9f-4e99-bd6e-510ae51341a7",
3
    "place": "{...}",
4
   "dataSource": "{...}",
5
   "score": 176
6
}

Delete Place

Use this method to delete a previously created place. Please note that the place associated with the specified docID only would be deleted. As a result, once a place is deleted, the search API can still return valid results from the default datasets or others, if present.

Request Parameters

Response Schema

Sample Request

1
curl --location --request DELETE 'https://api.nextbillion.io/multigeocode/place/MGA-d763feac-7b18-4bfb-b401-f27cea7154b6?key=yourapikey'

Sample Response

1
{
2
    "status": 200,
3
    "msg": "Ok"
4
}

API Query Limits

1. Only 100 queries can be added to the input while using the Batch Geocode endpoint.

2. NextBillion.ai allows a maximum rate limit of 2400 queries per minute or 40 queries/second for continuous requests, except for the Batch Geocode endpoint which is limited to 1 query/second.

   Note: We can increase the quota if needed on request. Contact [email protected] for more details.

API Error Codes