• Optimization
  • Navigation
  • Tracking
  • Maps
  • Places
  • Integrations

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

Sample Response

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

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

Use this method to provide a bunch of search queries and find the desired places using a single request. 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..

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

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

Sample Response

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

Get 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..

Response Schema

Loading..

Sample Request

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

Sample Response

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

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

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

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
      "docId": "MGA-d87c9011-4b9f-4e99-bd6e-510ae51341a7",
    "place": {
       "geopoint": {
           "lat": 17.414971,
           "lng": 78.427977
       },
       "country": "India",
       "state": "Telangana",
       "city": "",
       "district": "Hyderabad",
       "subDistrict": "",
       "street": "",
       "postalCode": "500035",
       "house": "",
       "building": "Police Department",
       "poi": {
           "title": "Telangana Police HQ"
       },
       "address": "Police Department,Hyderabad,Telangana,India,500035,Telangana Police HQ"
   },
   "dataSource": {
       "source": "NB",
       "refId": "150001",
       "status": "enable"
   },
   "score": 176
    }

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

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

Sample Response

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

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 support@nextbillion.ai for more details.

API Error Codes

Response CodeDescriptionAdditional Notes
200Normal success case.

Normal success case.

400Input validation failed.

Such as missing parameter or parameter with invalid value type (for example value cannot be parsed into number).

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.

422Could not process the request.

There is an underlying map issue which prevents the processing of the request.

429Too many requests.

QPM reached or API request count quota reached.

500Internal Service error.

There was an internal issue with NextBillion.ai services. You can reach out to support@nextbillion.ai for an explanation.

© 2024 NextBillion.ai all rights reserved.

Privacy Policy Terms of ServiceSLASupport Services Agreement