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,

Create custom locations that your business needs
Get combined results for a searched text from all data sources i.e default and custom datasets
Override the results of default search provider in case of duplicate or similar places and prioritize custom places in search results

POST

Search Place

The method enables searching for known places from multiple data sources

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.

https://api.nextbillion.io/multigeocode/search

Parameters

Request Parameters

Request Body

Response Schema

Sample Request

1curl --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        }'
12

Sample API Response

1
2        {
3            "entities": [
4                {
5                    "docId": "",
6                    "place": {
7                        "geopoint": {
8                            "lat": 17.39773,
9                            "lng": 78.48355
10                        },
11                        "country": "IND",
12                        "state": "Telangana",
13                        "city": "Hyderabad",
14                        "district": "Himayat Nagar",
15                        "subDistrict": "",
16                        "street": "Old M L A Quarters Road",
17                        "postalCode": "500029",
18                        "house": "",
19                        "building": "",
20                        "poi": {
21                            "title": "Dmart"
22                        },
23                        "address": "Dmart, Old M L A Quarters Road, Ap State Housing Board, Himayat Nagar, Hyderabad 500029, India"
24                    },
25                    "dataSource": {
26                        "source": "here",
27                        "refId": "here:pds:place:356tepfc-12a7da81897f5c5277a4df0f2bb28481",
28                        "status": "enable"
29                    },
30                    "score": "181"
31                }
32            ]
33        }
34

POST

Add A Place

The "Add Place" method allows users to create custom places

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’

https://api.nextbillion.io/multigeocode/place

Parameters

Request Parameters

Request Body

Response Schema

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              },
19              "dataSource": {
20                  "source": "NB",
21                  "refId": "150001",
22                  "status": "enable"
23              }
24            }'

Sample API Response

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

GET

Get Place

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

https://api.nextbillion.io/multigeocode/place/{docId}

Parameters

Request Parameters

Response Schema

Sample Request

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

Sample API 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"
19       },
20       "address": "Police Department,Hyderabad,Telangana,India,500035,Telangana Police HQ"
21   },
22   "dataSource": {
23       "source": "NB",
24       "refId": "150001",
25       "status": "enable"
26   },
27   "score": 176
28    }

PUT

Update Place

The "Update Place" method allows businesses to update the attributes of an existing place

This method allows you to update the attributes of custom places. In effect, updating a place replaces the current information in search results with the updated information associated with the specific docID. Use this method to enhance the accuracy/usability of your search results with respect to the default dataset to suit your business needs.

If you want to prioritize a particular result in your search results, update the ‘score’ of that specific place.
Alternatively, you can block places which are no longer needed by setting their status: ‘disable’.

https://api.nextbillion.io/multigeocode/place/{docId}

Parameters

Request Parameters

Request Body

Response Schema

Sample Request

1curl --location --request PUT 'https://api.nextbillion.io/multigeocode/place/MGA-41e325fd-77ee-475b-b386-9da926774e05?key=yourapikey'     --header 'Content-Type: application/json'     --data-raw '{
2          "place": {
3              "geopoint": {
4                  "lat": 22.4032134,
5                  "lng": 114.145293
6              },
7              "country": "china",
8              "state": "hk",
9              "district": "taimoshan",
10              "subDistrict": "",
11              "postalCode": "000-001",
12              "house": "#01",
13              "building": "building B",
14              "poi": {
15                  "title": "taimoshan"
16              }
17          },
18          "dataSource": {
19              "source": "here",
20              "refId": "here:cm:namedplace:23525085",
21              "status": "enable"
22          }
23      }'

Sample API Response

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

DELETE

Delete Place

The "Delete Place" method enables businesses to delete a previously created 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.

https://api.nextbillion.io/multigeocode/place/{docId}

Parameters

Request Parameters

Response Schema

Sample Request

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

Sample API Response

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

Query Limits

Generic Limits

Nextbillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests.

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

API Error Codes

Response Code	Description	Additional Notes
200	Normal success case.	Normal success case.
400	Input validation failed.	Such as missing parameter or parameter with invalid value type (for example value cannot be parsed into number).
401	APIKEY not supplied or invalid.	This error occurs when the wrong API key is passed in the request or the key is missing altogether
403	APIKEY 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.
404	Requested host/path not found.	This error occurs when there is a malformed host name used.
422	Could not process the request.	There is an underlying map issue which prevents the processing of the request.
429	Too many requests.	QPM reached or API request count quota reached.
500	Internal Service error.	There was an internal issue with NextBillion.ai services. You can reach out to [email protected] for an explanation.

Get Started

Geocode Postcode

Multi Geocoding API

Introduction

Parameters

Request Parameters

Request Body

Response Schema

Sample Request

Sample API Response

Parameters

Request Parameters

Request Body

Response Schema

Sample Request

Sample API Response

Parameters

Request Parameters

Response Schema

Sample Request

Sample API Response

Parameters

Request Parameters

Request Body

Response Schema

Sample Request

Sample API Response

Parameters

Request Parameters

Response Schema

Sample Request

Sample API Response

Query Limits

Generic Limits

API Error Codes

PLATFORM

SOLUTIONS

RESOURCES

COMPANY

UNITED STATES

SINGAPORE