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. Provide up to 10 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

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

Sample API 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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
[
   {
       "items": [
           {
               "title": "The White House",
               "id": "XOGTMt5u-Y6xOJMtBGDmCQ",
               "address": {
                   "label": "The White House, 1600 Pennsylvania Ave Nw, Washington, DC 20500, United States",
                   "countryCode": "USA",
                   "countryName": "United States",
                   "stateCode": "DC",
                   "state": "District of Columbia",
                   "county": "District of Columbia",
                   "city": "Washington",
                   "street": "Pennsylvania Ave Nw",
                   "postalCode": "20500-0005",
                   "houseNumber": "1600"
               },
               "scoring": {
                   "queryScore": 0.56,
                   "fieldScore": {
                       "state": 1,
                       "streets": [
                           0.67
                       ],
                       "houseNumber": 0.44,
                       "postalCode": 0.5
                   }
               },
               "position": {
                   "lat": 38.8977,
                   "lng": -77.03654
               },
               "access": [
                   {
                       "lat": 38.89877,
                       "lng": -77.0366
                   },
                   {
                       "lat": 38.89877,
                       "lng": -77.03671
                   },
                   {
                       "lat": 38.89877,
                       "lng": -77.03746
                   },
                   {
                       "lat": 38.89677,
                       "lng": -77.03363
                   }
               ],
               "mapView": {
                   "west": -77.03969,
                   "south": 38.89525,
                   "east": -77.03339,
                   "north": 38.90015
               },
               "categories": [
                   {
                       "id": "7376002",
                       "name": "important tourist attraction, building",
                       "primary": true
                   }
               ],
               "contacts": [
                   {
                       "phone": [
                           {
                               "value": "+1 202-456-1111"
                           }
                       ],
                       "www": [
                           {
                               "value": "www.whitehouse.gov"
                           }
                       ]
                   }
               ]
           }
       ]
   },
   {
       "items": [
           {
               "title": "Empire State Building",
               "id": "5GjOCyXMUOsLhBw6vwpo_Q",
               "address": {
                   "label": "Empire State Building, 350 5Th Ave, New York, NY 10118, United States",
                   "countryCode": "USA",
                   "countryName": "United States",
                   "stateCode": "NY",
                   "state": "New York",
                   "county": "New York",
                   "city": "New York",
                   "district": "Manhattan",
                   "street": "5Th Ave",
                   "postalCode": "10118-0104",
                   "houseNumber": "350"
               },
               "scoring": {
                   "queryScore": 0.49,
                   "fieldScore": {
                       "streets": [
                           0.73
                       ],
                       "houseNumber": 0.33,
                       "postalCode": 0.5
                   }
               },
               "position": {
                   "lat": 40.74816,
                   "lng": -73.985
               },
               "access": [
                   {
                       "lat": 40.74808,
                       "lng": -73.98482
                   },
                   {
                       "lat": 40.74812,
                       "lng": -73.98479
                   },
                   {
                       "lat": 40.74815,
                       "lng": -73.98594
                   }
               ],
               "mapView": {
                   "west": -73.98619,
                   "south": 40.74726,
                   "east": -73.98381,
                   "north": 40.74906
               },
               "categories": [
                   {
                       "id": "7376002",
                       "name": "important tourist attraction, building",
                       "primary": true
                   }
               ],
               "contacts": [
                   {
                       "phone": [
                           {
                               "value": "+1 212-736-3100"
                           }
                       ],
                       "www": [
                           {
                               "value": "www.esbnyc.com"
                           }
                       ]
                   }
               ]
           }
       ]
   },
   {
       "items": [
           {
               "title": "Whole Foods Market",
               "id": "7K48xVnDusK1oA6Udqrxmg",
               "address": {
                   "label": "Whole Foods Market, 2001 Market Street, San Francisco, CA 94114, United States",
                   "countryCode": "USA",
                   "countryName": "United States",
                   "stateCode": "CA",
                   "state": "California",
                   "county": "San Francisco",
                   "city": "San Francisco",
                   "street": "Market Street",
                   "postalCode": "94114-1316",
                   "houseNumber": "2001"
               },
               "scoring": {
                   "queryScore": 0.58,
                   "fieldScore": {
                       "streets": [
                           1
                       ],
                       "houseNumber": 1,
                       "postalCode": 0.56
                   }
               },
               "position": {
                   "lat": 37.76837,
                   "lng": -122.42713
               },
               "access": [
                   {
                       "lat": 37.7686,
                       "lng": -122.42741
                   }
               ],
               "mapView": {
                   "west": -122.42827,
                   "south": 37.76747,
                   "east": -122.42599,
                   "north": 37.76927
               },
               "categories": [
                   {
                       "id": "7332005",
                       "name": "market, supermarkets hypermarkets",
                       "primary": true
                   }
               ],
               "contacts": [
                   {
                       "phone": [
                           {
                               "value": "+1 415-626-1430"
                           }
                       ],
                       "www": [
                           {
                               "value": "www.wholefoodsmarket.com/"
                           }
                       ]
                   }
               ]
           }
       ]
   }
]

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}


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

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

API Query Limits

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

  2. NextBillion.ai allows a maximum rate limit of 6000 queries per minute or 100 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.