Discover API

Introduction

NextBillion.ai Discover API allows processing a free-form text query to look for matching addresses or places and return the results in order of relevance.

Request Parameters

Response Schema

Examples

Lets create a basic discover request in San Francisco area

Sample API Request

1
https://api.nextbillion.io/discover?key=<your_api_key>&at=37.78182,-122.45291&q=gas&limit=5&in=countryCode:USA,MEX

Sample API Response

1
{
2
   "items": [
3
       {
4
           "title": "Rc Gas",
5
           "id": "vVvq8TGB9Abonb1SYADenw",
6
           "address": {
7
               "label": "Rc Gas, 376 Castro Street, San Francisco, CA 94114, United States",
8
               "countryCode": "USA",
9
               "countryName": "United States",
10
               "stateCode": "CA",
11
               "state": "California",
12
               "county": "San Francisco",
13
               "city": "San Francisco",
14
               "street": "Castro Street",
15
               "postalCode": "94114-1524",
16
               "houseNumber": "376"
17
           },
18
           "scoring": {
19
               "queryScore": 0.9
20
           },
21
           "position": {
22
               "lat": 37.762951,
23
               "lng": -122.43554
24
           },
25
           "access": [
26
               {
27
                   "lat": 37.763,
28
                   "lng": -122.43521
29
               }
30
           ],
31
           "distance": 2594,
32
           "mapView": {
33
               "west": -122.43668,
34
               "south": 37.76205,
35
               "east": -122.4344,
36
               "north": 37.76385
37
           },
38
           "categories": [
39
               {
40
                   "id": "9150",
41
                   "name": "primary resource/utility",
42
                   "primary": true
43
               }
44
           ],
45
           "contacts": [
46
               {
47
                   "phone": [
48
                       {
49
                           "value": "+1 415-552-0103"
50
                       }
51
                   ]
52
               }
53
           ]
54
       },
55
       {
56
           "title": "Gas Light",
57
           "id": "E6Gri5mXYQ6Tgcr8o0D_nA",
58
           "address": {
59
               "label": "Gas Light, 3640 Buchanan Street, San Francisco, CA 94123, United States",
60
               "countryCode": "USA",
61
               "countryName": "United States",
62
               "stateCode": "CA",
63
               "state": "California",
64
               "county": "San Francisco",
65
               "city": "San Francisco",
66
               "street": "Buchanan Street",
67
               "postalCode": "94123-1709",
68
               "houseNumber": "3640"
69
           },
70
           "scoring": {
71
               "queryScore": 0.89
72
           },
73
           "position": {
74
               "lat": 37.803788,
75
               "lng": -122.433195
76
           },
77
           "access": [
78
               {
79
                   "lat": 37.80374,
80
                   "lng": -122.43346
81
               }
82
           ],
83
           "distance": 2994,
84
           "mapView": {
85
               "west": -122.43433,
86
               "south": 37.80289,
87
               "east": -122.43206,
88
               "north": 37.80469
89
           },
90
           "categories": [
91
               {
92
                   "id": "9150",
93
                   "name": "primary resource/utility",
94
                   "primary": true
95
               }
96
           ],
97
           "contacts": [
98
               {
99
                   "phone": [
100
                       {
101
                           "value": "+1 415-921-6138"
102
                       }
103
                   ]
104
               }
105
           ]
106
       },
107
       {
108
           "title": "Pacific Gas & Electric Co. Station J",
109
           "id": "5er0jZLp6gpXkDkesLDeeg",
110
           "address": {
111
               "label": "Pacific Gas & Electric Co. Station J, 565 Commercial Street, San Francisco, CA 94111, United States",
112
               "countryCode": "USA",
113
               "countryName": "United States",
114
               "stateCode": "CA",
115
               "state": "California",
116
               "county": "San Francisco",
117
               "city": "San Francisco",
118
               "street": "Commercial Street",
119
               "postalCode": "94111-3031",
120
               "houseNumber": "565"
121
           },
122
           "scoring": {
123
               "queryScore": 0.87
124
           },
125
           "position": {
126
               "lat": 37.79417,
127
               "lng": -122.402552
128
           },
129
           "access": [
130
               {
131
                   "lat": 37.79429,
132
                   "lng": -122.40257
133
               }
134
           ],
135
           "distance": 4633,
136
           "mapView": {
137
               "west": -122.40369,
138
               "south": 37.79327,
139
               "east": -122.40141,
140
               "north": 37.79507
141
           },
142
           "categories": [
143
               {
144
                   "id": "7376",
145
                   "name": "important tourist attraction",
146
                   "primary": true
147
               }
148
           ],
149
           "contacts": [
150
               {
151
                   "www": [
152
                       {
153
                           "value": "noehill.com/sf/landmarks/sf142.asp"
154
                       }
155
                   ]
156
               }
157
           ]
158
       },
159
       {
160
           "title": "Pacific Gas & Electric General Office Building",
161
           "id": "QCB98u8ILncy7m5w4FxzYw",
162
           "address": {
163
               "label": "Pacific Gas & Electric General Office Building, 245 East Market Street, Daly City, CA 94014, United States",
164
               "countryCode": "USA",
165
               "countryName": "United States",
166
               "stateCode": "CA",
167
               "state": "California",
168
               "county": "San Mateo",
169
               "city": "Daly City",
170
               "street": "East Market Street",
171
               "postalCode": "94014-2921",
172
               "houseNumber": "245"
173
           },
174
           "scoring": {
175
               "queryScore": 0.84
176
           },
177
           "position": {
178
               "lat": 37.690043,
179
               "lng": -122.462709
180
           },
181
           "access": [
182
               {
183
                   "lat": 37.68975,
184
                   "lng": -122.46274
185
               }
186
           ],
187
           "distance": 10241,
188
           "mapView": {
189
               "west": -122.46385,
190
               "south": 37.68914,
191
               "east": -122.46157,
192
               "north": 37.69094
193
           },
194
           "categories": [
195
               {
196
                   "id": "7376",
197
                   "name": "important tourist attraction",
198
                   "primary": true
199
               }
200
           ]
201
       },
202
       {
203
           "title": "Gas Light",
204
           "id": "XRGVho5J4YyexqZK7VdX1A",
205
           "address": {
206
               "label": "Gas Light, 3640 Buchanan Street, San Francisco, CA 94123, United States",
207
               "countryCode": "USA",
208
               "countryName": "United States",
209
               "stateCode": "CA",
210
               "state": "California",
211
               "county": "San Francisco",
212
               "city": "San Francisco",
213
               "street": "Buchanan Street",
214
               "postalCode": "94123-1709",
215
               "houseNumber": "3640"
216
           },
217
           "scoring": {
218
               "queryScore": 0.82
219
           },
220
           "position": {
221
               "lat": 37.803788,
222
               "lng": -122.433195
223
           },
224
           "access": [
225
               {
226
                   "lat": 37.80374,
227
                   "lng": -122.43346
228
               }
229
           ],
230
           "distance": 2994,
231
           "mapView": {
232
               "west": -122.43433,
233
               "south": 37.80289,
234
               "east": -122.43206,
235
               "north": 37.80469
236
           },
237
           "categories": [
238
               {
239
                   "id": "9361015",
240
                   "name": "shop, real estate agents",
241
                   "primary": true
242
               }
243
           ],
244
           "contacts": [
245
               {
246
                   "phone": [
247
                       {
248
                           "value": "+1 415-921-6138"
249
                       }
250
                   ]
251
               }
252
           ]
253
       }
254
   ]
255
}

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.