• Optimization
  • Navigation
  • Tracking
  • Maps
  • Places

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

POST

https://api.nextbillion.io/multigeocode/search?key={your_api_key}


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

Loading..

Request Body

Loading..

Response Schema

Loading..

Sample Request

1 curl --location --request POST 'https://api.nextbillion.io/multigeocode/search?key=yourapikey'
2 --header 'Content-Type: application/json'
3 --data '{
4 "query": "D-Mart",
5 "at": {
6 "lat": 17.3949,
7 "lng": 78.47072
8 },
9 "limit": 1,
10 "radius": "5km"
11 }'

Sample Response

1{
2 "entities": [
3 {
4 "docId": "",
5 "place": {
6 "geopoint": {
7 "lat": 17.39875,
8 "lng": 78.48191
9 },
10 "country": "IND",
11 "state": "Telangana",
12 "city": "Hyderabad",
13 "district": "Himayatnagar",
14 "subDistrict": "",
15 "street": "Hyderguda Main Road",
16 "postalCode": "500029",
17 "house": "",
18 "building": "",

Batch Geocode

POST

https://api.nextbillion.io/geocode/batch?key={your_api_key}


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

Loading..

Request Body

Loading..

Response Schema

Loading..

Sample Request

1curl --location 'https://api.nextbillion.io/h/geocode/batch?key=<your_api_key>'
2--header 'Content-Type: application/json'
3--data '[
4 {
5 "q": "The White House, DC",
6 "in": "countryCode:USA",
7 "lang": "en",
8 "limit": 1
9 },
10 {
11 "q": "Empire State Building",
12 "in": "countryCode:USA",
13 "lang": "en",
14 "limit": 1
15 },
16 {
17 "q": "Whole foods market, 2001",
18 "in": "countryCode:USA",

Sample API Response

1[
2 {
3 "items": [
4 {
5 "title": "The White House",
6 "id": "XOGTMt5u-Y6xOJMtBGDmCQ",
7 "address": {
8 "label": "The White House, 1600 Pennsylvania Ave Nw, Washington, DC 20500, United States",
9 "countryCode": "USA",
10 "countryName": "United States",
11 "stateCode": "DC",
12 "state": "District of Columbia",
13 "county": "District of Columbia",
14 "city": "Washington",
15 "street": "Pennsylvania Ave Nw",
16 "postalCode": "20500-0005",
17 "houseNumber": "1600"
18 },

Add A Place

POST

https://api.nextbillion.io/multigeocode/place?key={your_api_key}


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

Loading..

Request Body

Loading..

Response Schema

Loading..

Sample Request

1curl --location --request POST 'https://api.nextbillion.io/multigeocode/place?key=yourapikey'
2 --header 'Content-Type: application/json' --data-raw '{
3 "place": {
4 "geopoint": {
5 "lat": 17.414971242580236,
6 "lng": 78.42797703682547
7 },
8 "country": "India",
9 "state": "Telangana",
10 "district": "Hyderabad",
11 "subDistrict": "",
12 "postalCode": "500035",
13 "house": "",
14 "building": "Police Department",
15 "poi": {
16 "title": "Telangana Police HQ"
17 }
18 },

Sample Response

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

Get Place

POST

https://api.nextbillion.io/multigeocode/place?key={your_api_key}


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

Request Parameters

Loading..

Response Schema

Loading..

Sample Request

1curl --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

PUT

https://api.nextbillion.io/multigeocode/place/{docId}?key={your_api_key}


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

Loading..

Request Body

Loading..

Response Schema

Loading..

Sample Request

1curl --location --request PUT 'https://api.nextbillion.io/multigeocode/place/MGA-110a090c-657b-412d-a490-d3855322ff1b?key=your_api_key' \
2--header 'Content-Type: application/json' \
3--data '{
4 "place": {
5 "geopoint": {
6 "lat": 17.4576,
7 "lng": 78.3639
8 },
9 "country": "India",
10 "state": "Telangana",
11 "city": "Hyderabad",
12 "district": "Rangareddy",
13 "subDistrict": "Rangareddy",
14 "street": "Botanical Garden Road",
15 "postalCode": "500084",
16 "house": "",
17 "building": "Shopping Complex",
18 "poi": {

Sample Response

1{
2 "docId": "MGA-d87c9011-4b9f-4e99-bd6e-510ae51341a7",
3 "place": {
4 "geopoint": {
5 "lat": 17.414971,
6 "lng": 78.427977
7 },
8 "country": "India",
9 "state": "Telangana",
10 "city": "",
11 "district": "Hyderabad",
12 "subDistrict": "",
13 "street": "",
14 "postalCode": "500035",
15 "house": "",
16 "building": "Police Department",
17 "poi": {
18 "title": "Telangana Police HQ"

Delete Place

DELETE

https://api.nextbillion.io/multigeocode/place/{docId}?key={your_api_key}


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

Loading..

Response Schema

Loading..

Sample Request

1curl --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

Response CodeDescriptionAdditional Notes
200Normal success case.
Normal success case.
400Input validation failed.
There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.
401APIKEY not supplied or invalid.
This error occurs when the wrong API key is passed in the request or the key is missing altogether
403APIKEY is valid but does not have access to requested resources.
You might be querying for a geographical region which is not valid for your account, or requesting a service which is not enabled for you.
404Requested host/path not found.
This error occurs when there is a malformed host name used.
413Request entity too large
This error is caused when the length of input request URI or the request body is too large. Please modify the request. Reach out to [email protected] if the issue still persists.
422Could not process the request.
Could not process the request due to invalid search query or other parameter configurations. Please check the input values. Reach out to [email protected] for assistance if the issue persists.
429Too many requests.
QPM or API request count quota reached
500Internal Service error.
There was an internal issue with NextBillion.ai services. You can reach out to [email protected] for an explanation.