Autosuggest API
Introduction
This endpoint suggests address or place candidates based on an incomplete or misspelled query, from which the user selects the best query to submit.
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".
The API returns relevant suggestions to partial queries, such as "hosp", "London muse", "Times S" or "Par". The API returns two types of responses: query result items and entity result items.
-
Query result items cover the results for unknown places in a category, chain, or a location. These items return an
hrefelement containing a follow-up query for the Discover endpoint.
The query items are of two types:resultType: categoryQueryandresultType: chainQuery. -
Entity result items cover the results for known places. The entity result type can be one of places, locality, street, addressBlock, administrativeArea, and houseNumber. These items provide detailed information about the known place such as address, contact information and more.
NOTE: The response may contain experimental elements not documented here. Any undocumented element is subject to removal at any time.
Parameters
Loading...Response Schema
Loading...Query 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.
Examples
Sample API Request
1https://api.nextbillion.io/h/autosuggest?q=restaurant&at=51.509865,-0.118092&limit=5&key={{api_key}}Sample API Response
1{
2 "items": [
3 {
4 "title": "Riverfront Restaurant",
5 "id": "here:pds:place:826gcpuv-43eeb5893a954847928332d433595db3",
6 "resultType": "place",
7 "address": {
8 "label": "Riverfront Restaurant, South Bank, London, SE1 8XT, United Kingdom"
9 },
10 "position": {
11 "lat": 51.5075,
12 "lng": -0.11508
13 },
14 "access": [
15 {
16 "lat": 51.5075,
17 "lng": -0.11508
18 }
19 ],
20 "distance": 336,
21 "categories": [
22 {
23 "id": "100-1000-0000",
24 "name": "Restaurant",
25 "primary": true
26 },
27 {
28 "id": "100-1000-0007",
29 "name": "Cafeteria"
30 },
31 {
32 "id": "100-1100-0000",
33 "name": "Coffee/Tea"
34 },
35 {
36 "id": "200-2000-0011",
37 "name": "Bar or Pub"
38 }
39 ],
40 "references": [
41 {
42 "supplier": {
43 "id": "core"
44 },
45 "id": "1058638613"
46 },
47 {
48 "supplier": {
49 "id": "core"
50 },
51 "id": "1227363052"
52 },
53 {
54 "supplier": {
55 "id": "tripadvisor"
56 },
57 "id": "2361013"
58 },
59 {
60 "supplier": {
61 "id": "yelp"
62 },
63 "id": "x6GRfK94vE6RjNsPjvJSCg"
64 }
65 ],
66 "foodTypes": [
67 {
68 "id": "308-000",
69 "name": "British Isles",
70 "primary": true
71 },
72 {
73 "id": "304-000",
74 "name": "Italian"
75 },
76 {
77 "id": "800-061",
78 "name": "Breakfast"
79 },
80 {
81 "id": "800-064",
82 "name": "International"
83 }
84 ],
85 "highlights": {
86 "title": [
87 {
88 "start": 11,
89 "end": 21
90 }
91 ],
92 "address": {
93 "label": [
94 {
95 "start": 11,
96 "end": 21
97 }
98 ]
99 }
100 }
101 },
102 {
103 "title": "Oxo Tower Restaurant",
104 "id": "here:pds:place:826gcpvj-7b00ccb5e87a48738f64b39c91635233",
105 "resultType": "place",
106 "address": {
107 "label": "Oxo Tower Restaurant, Barge House Street, London, SE1 9, United Kingdom"
108 },
109 "position": {
110 "lat": 51.50837,
111 "lng": -0.10828
112 },
113 "access": [
114 {
115 "lat": 51.50794,
116 "lng": -0.10871
117 }
118 ],
119 "distance": 699,
120 "categories": [
121 {
122 "id": "100-1000-0000",
123 "name": "Restaurant",
124 "primary": true
125 },
126 {
127 "id": "700-7250-0136",
128 "name": "Business Facility"
129 }
130 ],
131 "references": [
132 {
133 "supplier": {
134 "id": "core"
135 },
136 "id": "1024315250"
137 },
138 {
139 "supplier": {
140 "id": "core"
141 },
142 "id": "1176312433"
143 }
144 ],
145 "foodTypes": [
146 {
147 "id": "308-000",
148 "name": "British Isles",
149 "primary": true
150 },
151 {
152 "id": "304-000",
153 "name": "Italian"
154 },
155 {
156 "id": "306-000",
157 "name": "Austrian"
158 }
159 ],
160 "highlights": {
161 "title": [
162 {
163 "start": 10,
164 "end": 20
165 }
166 ],
167 "address": {
168 "label": [
169 {
170 "start": 10,
171 "end": 20
172 }
173 ]
174 }
175 }
176 },
177 {
178 "title": "Restaurant",
179 "id": "here:cm:ontology:restaurant",
180 "resultType": "categoryQuery",
181 "href": "https://api.nextbillion.io/h/discover?at=51.509865%2C-0.118092&limit=5&q=Restaurant&_ontology=restaurant",
182 "highlights": {
183 "title": [
184 {
185 "start": 0,
186 "end": 10
187 }
188 ]
189 }
190 },
191 {
192 "title": "St Martins Lane Hotel (The Restaurant at St Martins Lane London)",
193 "id": "here:pds:place:826gcpvj-31990afb834449248dfc54a6152ea081",
194 "resultType": "place",
195 "address": {
196 "label": "St Martins Lane Hotel, 45 St Martin's Lane, London, WC2N 4, United Kingdom"
197 },
198 "position": {
199 "lat": 51.51051,
200 "lng": -0.12674
201 },
202 "access": [
203 {
204 "lat": 51.5105,
205 "lng": -0.12695
206 }
207 ],
208 "distance": 603,
209 "categories": [
210 {
211 "id": "500-5000-0053",
212 "name": "Hotel",
213 "primary": true
214 },
215 {
216 "id": "100-1000-0000",
217 "name": "Restaurant"
218 },
219 {
220 "id": "200-2000-0011",
221 "name": "Bar or Pub"
222 },
223 {
224 "id": "200-2200-0000",
225 "name": "Theatre, Music and Culture"
226 },
227 {
228 "id": "500-5000-0000",
229 "name": "Hotel/Motel"
230 },
231 {
232 "id": "500-5100-0000",
233 "name": "Lodging"
234 }
235 ],
236 "references": [
237 {
238 "supplier": {
239 "id": "core"
240 },
241 "id": "546206042"
242 },
243 {
244 "supplier": {
245 "id": "core"
246 },
247 "id": "546208698"
248 },
249 {
250 "supplier": {
251 "id": "tripadvisor"
252 },
253 "id": "17700576"
254 },
255 {
256 "supplier": {
257 "id": "tripadvisor"
258 },
259 "id": "193107"
260 },
261 {
262 "supplier": {
263 "id": "yelp"
264 },
265 "id": "41O4t10hkBaqJEwuMzunNg"
266 },
267 {
268 "supplier": {
269 "id": "yelp"
270 },
271 "id": "SjGYpd_bzEYDW9PkMzvE_g"
272 }
273 ],
274 "foodTypes": [
275 {
276 "id": "800-064",
277 "name": "International",
278 "primary": true
279 },
280 {
281 "id": "101-000",
282 "name": "American"
283 },
284 {
285 "id": "200-000",
286 "name": "Asian"
287 },
288 {
289 "id": "300-000",
290 "name": "European"
291 },
292 {
293 "id": "308-000",
294 "name": "British Isles"
295 },
296 {
297 "id": "800-066",
298 "name": "Fusion"
299 }
300 ],
301 "highlights": {
302 "title": [
303 {
304 "start": 27,
305 "end": 37
306 }
307 ],
308 "address": {
309 "label": []
310 }
311 }
312 },
313 {
314 "title": "Rules",
315 "id": "here:pds:place:826gcpvj-b93b5fcb2491425688cd72b28fbe00f3",
316 "resultType": "place",
317 "address": {
318 "label": "Rules, 35 Maiden Lane, London, WC2E 7LB, United Kingdom"
319 },
320 "position": {
321 "lat": 51.51088,
322 "lng": -0.12309
323 },
324 "access": [
325 {
326 "lat": 51.51078,
327 "lng": -0.12298
328 }
329 ],
330 "distance": 364,
331 "categories": [
332 {
333 "id": "100-1000-0000",
334 "name": "Restaurant",
335 "primary": true
336 }
337 ],
338 "references": [
339 {
340 "supplier": {
341 "id": "core"
342 },
343 "id": "1176324520"
344 },
345 {
346 "supplier": {
347 "id": "tripadvisor"
348 },
349 "id": "700845"
350 },
351 {
352 "supplier": {
353 "id": "yelp"
354 },
355 "id": "Ds183PwKYB6PXSygM2N-EA"
356 },
357 {
358 "supplier": {
359 "id": "yelp"
360 },
361 "id": "mn9JQh5w5I9YGXqHn0PbfQ"
362 }
363 ],
364 "foodTypes": [
365 {
366 "id": "308-000",
367 "name": "British Isles",
368 "primary": true
369 },
370 {
371 "id": "300-000",
372 "name": "European"
373 },
374 {
375 "id": "503-000",
376 "name": "Ethiopian"
377 },
378 {
379 "id": "800-064",
380 "name": "International"
381 }
382 ],
383 "highlights": {
384 "title": [],
385 "address": {
386 "label": []
387 }
388 }
389 }
390 ],
391 "queryTerms": []
392}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. |
