Autosuggest API

Introduction

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:

unknown places from a category or chain, such as "hospitals".
unknown places at known locations, such as "London museums".
known places with known names, such as "Times Square" or "Paris".
known and unknown places for partial queries, such as "hosp", "London muse", "Times S" or "Par"

NOTE: The response may contain experimental elements not documented here. Any undocumented element is subject to removal at any time.

Request Parameters

Response Schema

Examples

Let’s search for a mis-spelled query looking for “aquariums” 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

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 Code	Description	Additional 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.