Autosuggestion APIs

Introduction

NextBillion.ai provides two useful methods to help users complete their places search faster. The Autosuggest API can suggest places based on incomplete queries while the Autocomplete API helps complete the entered keystrokes while typing in a search query. Both these APIs return complete place details that qualify as valid suggestions for the given input.

Let’s cover both of them in detail in the following sections.

Autosuggest API

Nextbillion.ai Autosuggest API proposes address or place candidates based on an incomplete or misspelled query, from which the user can select the best query to submit for a full search.

The Autosuggest API provides comprehensive responses to free-form user queries by returning suggestions for:

  1. unknown places from a category or chain, such as "hospitals".

  2. unknown places at known locations, such as "London museums".

  3. known places with known names, such as "Times Square" or "Paris".

  4. known and unknown places for partial queries, such as "hosp", "London muse", "Times S" or "Par"

GET

https://api.nextbillion.io/autosuggest?q={search_query}&key={your_api_key}

Request Parameters

Loading..

Response Schema

Loading..

Examples

Let’s search for a mis-spelled query looking for “aqauriums” in the Boston city region.

Sample API Request

1
curl --location 'https://api.nextbillion.io/autosuggest?at=42.350133,-71.068900&key=<your_api_key>&limit=5&q=aqauriums'

Sample API Response

1
{
2
   "items": [
3
       {
4
           "title": "Aquarium Station",
5
           "id": "47_E4Ni11pElGqRAU6PTcQ",
6
           "address": {
7
               "label": "Aquarium Station, 183 State Street, Boston, MA 02109, United States",
8
               "countryCode": "USA",
9
               "countryName": "United States",
10
               "stateCode": "MA",
11
               "state": "Massachusetts",
12
               "county": "Suffolk",
13
               "city": "Boston",
14
               "street": "State Street",
15
               "postalCode": "02109-2600",
16
               "houseNumber": "183"
17
           },
18
           "scoring": {
19
               "queryScore": 0.98
20
           },
21
           "position": {
22
               "lat": 42.359258,
23
               "lng": -71.053041
24
           },
25
           "access": [
26
               {
27
                   "lat": 42.35941,
28
                   "lng": -71.05317
29
               },
30
               {
31
                   "lat": 42.35944,
32
                   "lng": -71.05299
33
               }
34
           ],
35
           "distance": 1651,
36
           "mapView": {
37
               "west": -71.05426,
38
               "south": 42.35836,
39
               "east": -71.05182,
40
               "north": 42.36016
41
           },
42
           "categories": [
43
               {
44
                   "id": "7380005",
45
                   "name": "railway station, metro",
46
                   "primary": true
47
               }
48
           ],
49
           "contacts": [
50
               {
51
                   "www": [
52
                       {
53
                           "value": "www.mbta.com"
54
                       }
55
                   ]
56
               }
57
           ]
58
       },
59
       {
60
           "title": "New England Aquarium",
61
           "id": "Ts9B7UN1-hbVIWrSOwpr9Q",
62
           "address": {
63
               "label": "New England Aquarium, 1 Central Wharf, Boston, MA 02110, United States",
64
               "countryCode": "USA",
65
               "countryName": "United States",
66
               "stateCode": "MA",
67
               "state": "Massachusetts",
68
               "county": "Suffolk",
69
               "city": "Boston",
70
               "street": "Central Wharf",
71
               "postalCode": "02110-3309",
72
               "houseNumber": "1"
73
           },
74
           "scoring": {
75
               "queryScore": 0.95
76
           },
77
           "position": {
78
               "lat": 42.359171,
79
               "lng": -71.049536
80
           },
81
           "access": [
82
               {
83
                   "lat": 42.35899,
84
                   "lng": -71.05067
85
               }
86
           ],
87
           "distance": 1881,
88
           "mapView": {
89
               "west": -71.05075,
90
               "south": 42.35827,
91
               "east": -71.04832,
92
               "north": 42.36007
93
           },
94
           "categories": [
95
               {
96
                   "id": "7317",
97
                   "name": "museum",
98
                   "primary": true
99
               }
100
           ],
101
           "contacts": [
102
               {
103
                   "phone": [
104
                       {
105
                           "value": "+1 617-973-5200"
106
                       }
107
                   ]
108
               }
109
           ]
110
       },
111
       {
112
           "title": "New England Aquarium Corporation",
113
           "id": "TUkbCLOpM0rMScHtwM8LdA",
114
           "address": {
115
               "label": "New England Aquarium Corporation, Central Wharf, Boston, MA 02110, United States",
116
               "countryCode": "USA",
117
               "countryName": "United States",
118
               "stateCode": "MA",
119
               "state": "Massachusetts",
120
               "county": "Suffolk",
121
               "city": "Boston",
122
               "street": "Central Wharf",
123
               "postalCode": "02110"
124
           },
125
           "scoring": {
126
               "queryScore": 0.91
127
           },
128
           "position": {
129
               "lat": 42.359059,
130
               "lng": -71.050393
131
           },
132
           "access": [
133
               {
134
                   "lat": 42.35897,
135
                   "lng": -71.05037
136
               }
137
           ],
138
           "distance": 1816,
139
           "mapView": {
140
               "west": -71.05161,
141
               "south": 42.35816,
142
               "east": -71.04918,
143
               "north": 42.35996
144
           },
145
           "categories": [
146
               {
147
                   "id": "9927004",
148
                   "name": "zoos, arboreta botanical garden, aquatic zoo marine park",
149
                   "primary": true
150
               }
151
           ],
152
           "contacts": [
153
               {
154
                   "phone": [
155
                       {
156
                           "value": "+1 617-573-9352"
157
                       }
158
                   ],
159
                   "www": [
160
                       {
161
                           "value": "www.neaq.org"
162
                       }
163
                   ]
164
               }
165
           ]
166
       },
167
       {
168
           "title": "Aquarium",
169
           "id": "3q7eeRuiA2diuKGM4A8HPg",
170
           "address": {
171
               "label": "Aquarium, State Street, Boston, MA 02110, United States",
172
               "countryCode": "USA",
173
               "countryName": "United States",
174
               "stateCode": "MA",
175
               "state": "Massachusetts",
176
               "county": "Suffolk",
177
               "city": "Boston",
178
               "street": "State Street",
179
               "postalCode": "02110"
180
           },
181
           "scoring": {
182
               "queryScore": 0.89
183
           },
184
           "position": {
185
               "lat": 42.359784,
186
               "lng": -71.051652
187
           },
188
           "access": [
189
               {
190
                   "lat": 42.35965,
191
                   "lng": -71.05163
192
               }
193
           ],
194
           "distance": 1777,
195
           "mapView": {
196
               "west": -71.05287,
197
               "south": 42.35888,
198
               "east": -71.05043,
199
               "north": 42.36068
200
           },
201
           "categories": [
202
               {
203
                   "id": "9942002",
204
                   "name": "public transport stop, bus stop",
205
                   "primary": true
206
               }
207
           ]
208
       },
209
       {
210
           "title": "Aquarium World",
211
           "id": "VibMZDqzu3wol7_ymL3o8g",
212
           "address": {
213
               "label": "Aquarium World, 281 Mount Auburn Street, Watertown, MA 02472, United States",
214
               "countryCode": "USA",
215
               "countryName": "United States",
216
               "stateCode": "MA",
217
               "state": "Massachusetts",
218
               "county": "Middlesex",
219
               "city": "Watertown",
220
               "street": "Mount Auburn Street",
221
               "postalCode": "02472-1955",
222
               "houseNumber": "281"
223
           },
224
           "scoring": {
225
               "queryScore": 0.69
226
           },
227
           "position": {
228
               "lat": 42.369498,
229
               "lng": -71.172359
230
           },
231
           "access": [
232
               {
233
                   "lat": 42.36967,
234
                   "lng": -71.17248
235
               }
236
           ],
237
           "distance": 8769,
238
           "mapView": {
239
               "west": -71.17358,
240
               "south": 42.3686,
241
               "east": -71.17114,
242
               "north": 42.3704
243
           },
244
           "categories": [
245
               {
246
                   "id": "9927004",
247
                   "name": "zoos, arboreta botanical garden, aquatic zoo marine park",
248
                   "primary": true
249
               }
250
           ],
251
           "contacts": [
252
               {
253
                   "phone": [
254
                       {
255
                           "value": "+1 617-600-3434"
256
                       }
257
                   ]
258
               }
259
           ]
260
       }
261
   ]
262
}
263

Autocomplete API

Introduction

NextBillion.ai Autocomplete API completes valid street addresses or administrative areas using the entered keystrokes to speed-up the process of completing the address search queries.

GET

https://api.nextbillion.io/autocomplete?q={search_query}&key={your_api_key}

Request Parameters

Loading..

Response Schema

Loading..

Examples

Let’s look for places containing stat word in their names in Oklahoma City region

Sample API Request

1
curl --location 'https://api.nextbillion.io/autocomplete?q=stat&at=35.476911,-97.487201&limit=5&in=countryCode:USA, MEX&key=<your_api_key>'

Sample API Response

1
{
2
   "items": [
3
       {
4
           "title": "State Capitol",
5
           "id": "qN08rVNZIciFxFJeg3hgow",
6
           "address": {
7
               "label": "State Capitol, 2300 North Lincoln Boulevard, Oklahoma City, OK 73105, United States",
8
               "countryCode": "USA",
9
               "countryName": "United States",
10
               "stateCode": "OK",
11
               "state": "Oklahoma",
12
               "county": "Oklahoma",
13
               "city": "Oklahoma City",
14
               "street": "North Lincoln Boulevard",
15
               "postalCode": "73105-4805",
16
               "houseNumber": "2300"
17
           },
18
           "scoring": {
19
               "queryScore": 1
20
           },
21
           "position": {
22
               "lat": 35.491815,
23
               "lng": -97.503339
24
           },
25
           "access": [
26
               {
27
                   "lat": 35.49114,
28
                   "lng": -97.50331
29
               },
30
               {
31
                   "lat": 35.49158,
32
                   "lng": -97.50149
33
               }
34
           ],
35
           "distance": 2209,
36
           "mapView": {
37
               "west": -97.50521,
38
               "south": 35.49029,
39
               "east": -97.50147,
40
               "north": 35.49334
41
           },
42
           "categories": [
43
               {
44
                   "id": "7376",
45
                   "name": "important tourist attraction",
46
                   "primary": true
47
               }
48
           ],
49
           "contacts": [
50
               {
51
                   "www": [
52
                       {
53
                           "value": "www.okhouse.gov/Information/CapitolTours.aspx"
54
                       }
55
                   ]
56
               }
57
           ]
58
       },
59
       {
60
           "title": "United States Postal Service",
61
           "id": "wFfRtLgHYeJfAoKawwoNKw",
62
           "address": {
63
               "label": "United States Postal Service, 701 North Kelley Avenue, Oklahoma City, OK 73117, United States",
64
               "countryCode": "USA",
65
               "countryName": "United States",
66
               "stateCode": "OK",
67
               "state": "Oklahoma",
68
               "county": "Oklahoma",
69
               "city": "Oklahoma City",
70
               "street": "North Kelley Avenue",
71
               "postalCode": "73117-1400",
72
               "houseNumber": "701"
73
           },
74
           "scoring": {
75
               "queryScore": 0.99
76
           },
77
           "position": {
78
               "lat": 35.473932,
79
               "lng": -97.495284
80
           },
81
           "access": [
82
               {
83
                   "lat": 35.47393,
84
                   "lng": -97.49517
85
               }
86
           ],
87
           "distance": 803,
88
           "mapView": {
89
               "west": -97.49639,
90
               "south": 35.47303,
91
               "east": -97.49418,
92
               "north": 35.47483
93
           },
94
           "categories": [
95
               {
96
                   "id": "7324003",
97
                   "name": "post office, local",
98
                   "primary": true
99
               }
100
           ],
101
           "contacts": [
102
               {
103
                   "phone": [
104
                       {
105
                           "value": "+1 405-236-0534"
106
                       }
107
                   ],
108
                   "www": [
109
                       {
110
                           "value": "www.usps.com"
111
                       }
112
                   ]
113
               }
114
           ]
115
       },
116
       {
117
           "title": "Staton Drive, Oklahoma City, OK 73111, United States",
118
           "id": "hDHq2NbnFEtoP5otpkeQIA",
119
           "address": {
120
               "label": "Staton Drive, Oklahoma City, OK 73111, United States",
121
               "countryCode": "USA",
122
               "countryName": "United States",
123
               "stateCode": "OK",
124
               "state": "Oklahoma",
125
               "county": "Oklahoma",
126
               "city": "Oklahoma City",
127
               "street": "Staton Drive",
128
               "postalCode": "73111"
129
           },
130
           "scoring": {
131
               "queryScore": 0.99
132
           },
133
           "position": {
134
               "lat": 35.510759,
135
               "lng": -97.489053
136
           },
137
           "access": [
138
               {
139
                   "lat": 35.510759,
140
                   "lng": -97.489053
141
               }
142
           ],
143
           "distance": 3767,
144
           "mapView": {
145
               "west": -97.48995,
146
               "south": 35.50959,
147
               "east": -97.48813,
148
               "north": 35.51154
149
           }
150
       },
151
       {
152
           "title": "Jeremy Henley - State Farm",
153
           "id": "U1yvkrTAXTeIhgXRPkagVQ",
154
           "address": {
155
               "label": "Jeremy Henley - State Farm, 114 Northwest 6th Street, Oklahoma City, OK 73102, United States",
156
               "countryCode": "USA",
157
               "countryName": "United States",
158
               "stateCode": "OK",
159
               "state": "Oklahoma",
160
               "county": "Oklahoma",
161
               "city": "Oklahoma City",
162
               "street": "Northwest 6th Street",
163
               "postalCode": "73102-6015",
164
               "houseNumber": "114"
165
           },
166
           "scoring": {
167
               "queryScore": 0.96
168
           },
169
           "position": {
170
               "lat": 35.473743,
171
               "lng": -97.515228
172
           },
173
           "access": [
174
               {
175
                   "lat": 35.47399,
176
                   "lng": -97.51512
177
               },
178
               {
179
                   "lat": 35.47399,
180
                   "lng": -97.51512
181
               }
182
           ],
183
           "distance": 2562,
184
           "mapView": {
185
               "west": -97.51633,
186
               "south": 35.47284,
187
               "east": -97.51412,
188
               "north": 35.47464
189
           },
190
           "categories": [
191
               {
192
                   "id": "9352007",
193
                   "name": "insurance, company",
194
                   "primary": true
195
               }
196
           ],
197
           "contacts": [
198
               {
199
                   "phone": [
200
                       {
201
                           "value": "+1 405-605-4466"
202
                       }
203
                   ],
204
                   "www": [
205
                       {
206
                           "value": "www.jeremyhenley.com"
207
                       }
208
                   ]
209
               }
210
           ]
211
       },
212
       {
213
           "title": "Statesboro, GA, United States",
214
           "id": "a60FRgx3mffb2MWJWEcFUg",
215
           "address": {
216
               "label": "Statesboro, GA, United States",
217
               "countryCode": "USA",
218
               "countryName": "United States",
219
               "stateCode": "GA",
220
               "state": "Georgia",
221
               "county": "Bulloch",
222
               "city": "Statesboro"
223
           },
224
           "scoring": {
225
               "queryScore": 0.95
226
           },
227
           "position": {
228
               "lat": 32.44877,
229
               "lng": -81.777753
230
           },
231
           "access": [
232
               {
233
                   "lat": 32.44877,
234
                   "lng": -81.777753
235
               }
236
           ],
237
           "distance": 1485645,
238
           "mapView": {
239
               "west": -81.97639,
240
               "south": 32.26011,
241
               "east": -81.52527,
242
               "north": 32.65335
243
           }
244
       }
245
   ]
246
}
247

API Query Limits

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

API Error Codes

Response CodeDescriptionAdditional Notes
200

Normal success case.

Normal success case

400

Input validation failed.

There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.

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 a malformed hostname is used.

422

Could not process the request.

Valid results could not be generated for the given parameters. Please modify the constraints/search query.

429

Too many requests.

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

PRODUCTS
SOLUTIONS
COMPARE
DEVELOPERS
GUIDES
RESOURCES
COMPANY
logo
UNITED STATES

NEXTBILLION.AI, INC.
21 E State Street,
Suite 200,
Columbus, OH 43215

SINGAPORE

#32-01, 80 Raffles Place, UOB Plaza,
Singapore, 048624

© 2025 NextBillion.ai all rights reserved.

Privacy PolicyTerms of ServiceSLASupport Services Agreement