Geofence API
API Overview
NextBillion.ai's Geofence API is a robust solution that enables users to establish and control custom geographical boundaries, commonly referred to as geofences, on a digital map. With this API, businesses can define areas of interest and use them for meeting various business needs. Businesses involved in providing location-based services, fleet management, asset tracking services, or logistics services can use the Geofence API to improve their operations, enhance customer experiences, and increase efficiency.
With NextBillions's Geofence API, businesses can easily create, modify and delete geofences of three types - circle, custom polygon, or isochrone based geofences on a map. Let’s take a look at the Geofence API’s methods and their properties.
Create a Geofence
Use this method to create a new geofence through a POST request containing the necessary parameters in the request body. The parameters typically include information such as the type of geofence, its name, tags, and the geographical coordinates defining its boundary. Users can create circular, custom polygon or isochrone based geofences. Once the request is processed successfully, the geofence is created and can be used for a variety of location-based services such as geotargeting, asset tracking, and more
Request Parameter
Loading...Request Body
Loading...Response Schema
Loading...Example 1-Create a circle Geofence
Let’s create a circle type geofence around a hotel’s location. In the request we:
-
set a location coordinate as the
centerof the circular geofence. -
define the
radiusof a circular geofence -
set the
typeof the geofence ascircle. -
add meaningful
tags,meta_dataandname
Request
1curl --location --request POST 'https://api.nextbillion.io/geofence?key=<your_api_key>'
2 --header 'Content-Type: application/json'
3 --data-raw '{
4 "circle": {
5 "center": {
6 "lat":34.052799,
7 "lon":-118.255235
8 },
9 "radius": 5000
10 },
11 "meta_data": {"building":"yes",
12 "building_name":"The Westin Bonaventure Hotel & Suites, Los Angeles"},
13 "name": "The Westin Hotel staff transportation",
14 "tags": [
15 "Hotel-staff",
16 "Free_transportation_service"
17 ],
18 "type": "circle"
19 }'Response
1{
2 "status": "Ok",
3 "data": {
4 "id": "1287cd61-fc73-48d2-a82f-6bb4eb0d6f69"
5 }
6}Example 2-Create an isochrone Geofence
Let’s create an isochrone type geofence around a hotel’s location. In the request we:
-
set location
coordinateswhich would act as the starting point to determine the isochrone. -
set
contours_minuteto determine the driving time and consequently the isochrone boundaries. -
add a
departure_timeto set the typical traffic conditions for which isochrone needs to be configured. -
set the
typeof the geofence asisochrone. -
add meaningful
tags,meta_dataandname
Request
1curl --location --request POST 'https://api.nextbillion.io/geofence?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data-raw '{
4 "isochrone": {
5 "coordinates":"34.0453,-118.2666",
6 "departure_time": 1691407800,
7 "mode": "car",
8 "denoise": 0.8,
9 "contours_minute": 30
10 },
11 "meta_data": {
12 "purpose":"isochrone_example_geofence",
13 "area": "Los Angeles"
14 },
15 "type": "isochrone",
16 "tags": [
17 "delivery",
18 "vehicle"
19 ],
20 "name": "The Ritz Carlton, Los Angeles isochrone"
21}'Request
1"status": "Ok",
2"data": {
3"id": "409f7e0e-4cef-461c-84e1-b3715a5610d1"
4}
5}Example 3-Create a polygon Geofence
Let’s create an polygon type geofence around a hotel’s location. In the request we:
-
provide
geojsondetails of the polygon that we want to convert into a geofence. -
set the
typeof the geofence aspolygon. -
add meaningful
tags,meta_dataandname
Request
1curl --location --request POST 'https://api.nextbillion.io/geofence?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data-raw '{
4 "polygon":{
5 "geojson":{
6 "type":"Polygon",
7 "coordinates":[
8 [
9 [
10 -118.268312,
11 34.046253
12 ],
13 [
14 -118.269707,
15 34.045097
16 ],
17 [
18 -118.270963,
19 34.042996
20 ],
21 [
22 -118.266940,
23 34.042149
24 ],
25 [
26 -118.264289,
27 34.044904
28 ],
29 [
30 -118.264661,
31 34.046638
32 ],
33 [
34 -118.266777,
35 34.047255
36 ],
37 [
38 -118.268312,
39 34.046253
40 ]
41 ]
42 ]
43 }
44 },
45 "meta_data": {
46 "purpose":"plolygon_example_geofence",
47 "area": "Los Angeles"
48 },
49 "type": "polygon",
50 "tags": [
51 "delivery",
52 "vehicle"
53 ],
54 "name": "The Ritz Carlton, Los Angeles polygon"
55}'Response
1{
2"status": "Ok",
3"data": {
4"id": "24760549-e83d-4ba2-82f3-3a3f3459799d"
5}
6}Batch Create Geofences
Use this method to create geofences in bulk by sending a POST request containing an array with details of each geofence to be created in the request body. This method is helpful in easily creating up to 100 geofences with only a single request. Users can also provide custom IDs for the geofences or else they can rely on the service to create auto-generated IDs. The service will respond with the IDs of the newly created geofences.
Request Parameter
Loading...Request Body
Loading...Response Schema
Loading...Example-Batch Create Geofence
Let’s create a request for creating one geofences of each type using the following parameters:
Request
1curl --location 'https://api.nextbillion.io/geofence/batch?key=<your_api_key>'
2--header 'Content-Type: application/json; charset=utf-8'
3--data '{
4 "geofences": [
5 {
6 "custom_id": "test_batch_geofence_1",
7 "isochrone": {
8 "contours_meter": 25000,
9 "denoise": 0.8,
10 "mode": "car",
11 "coordinates": "34.05067078,-118.24781414"
12 },
13 "tags": [
14 "test_tag_1",
15 "test_tag_2"
16 ],
17 "type": "isochrone",
18 "name": "Los_Angeles_Downtown_isochrone"
19 },
20 {
21 "custom_id": "test_batch_geofence_2",
22 "tags": [
23 "test_tag_2",
24 "test_tag_3"
25 ],
26 "circle": {
27 "center": {
28 "lon": -118.24781414,
29 "lat": 34.05067078
30 },
31 "radius": 150
32 },
33 "type": "circle",
34 "name": "Los_Angeles_Downtown_circle"
35 },
36 {
37 "custom_id": "test_batch_geofence_3",
38 "polygon": {
39 "geojson": {
40 "type": "Polygon",
41 "coordinates": [
42 [
43 [
44 -118.25192611,
45 34.05493859
46 ],
47 [
48 -118.25672277,
49 34.05083373
50 ],
51 [
52 -118.25688055,
53 34.04518596
54 ],
55 [
56 -118.2533329,
57 34.04268422
58 ],
59 [
60 -118.24779707,
61 34.04266453
62 ],
63 [
64 -118.24525487,
65 34.04565692
66 ],
67 [
68 -118.24363926,
69 34.04929884
70 ],
71 [
72 -118.25192611,
73 34.05493859
74 ]
75 ]
76 ]
77 }
78 },
79 "tags": [
80 "test_tag_1",
81 "test_tag_2"
82 ],
83 "type": "polygon",
84 "name": "Los_Angeles_Downtown_polygon"
85 }
86 ]
87}'Response
1{
2 "status": "Ok",
3 "data": {
4 "ids": [
5 "test_batch_geofence_1",
6 "test_batch_geofence_2",
7 "test_batch_geofence_3"
8 ]
9 }
10}Get a Geofence
Use this method to find an existing geofence using its ID through a GET request containing the ID of the geofence as a path parameter. Once the request is processed successfully, the API will return the details of the geofence, which typically include information such as the type of geofence, its name, tags, and the geographical coordinates defining its boundary. This method can be useful for retrieving information about a geofence that was previously created and is needed for further processing or analysis.
Request Parameter
Loading...Response Schema
Loading...Example-Get a Geofence
Let’s retrieve a previously created geofence using its ID.
Request
curl --location --request GET 'https://api.nextbillion.io/geofence/0d469774-0c7e-411d-93d0-f1a5a1f3be16?key=<your_api_key>'Response
1{
2 "status": "Ok",
3 "data": {
4 "geofence": {
5 "id": "0d469774-0c7e-411d-93d0-f1a5a1f3be16",
6 "name": "SF-loc1",
7 "type": "polygon",
8 "geojson": {
9 "type": "Polygon",
10 "coordinates": [
11 [
12 [-122.428554017, 37.787002428],
13 [-122.428065855, 37.787013027],
14 [-122.428151685, 37.787383979],
15 [-122.428755182, 37.787275873],
16 [-122.428554017, 37.787002428]
17 ]
18 ]
19 },
20 "tags": ["source"],
21 "created_at": 1684310763,
22 "updated_at": 1684310763,
23 "meta_data": {
24 "country": "USA,San Francisco"
25 }
26 }
27 }
28}Get Multiple Geofences
Use this method to search and retrieve several geofences using their IDs by sending a GET request containing the list of geofence IDs to be retrieved as a request parameter. This method can be helpful in quickly looking for multiple geofences in a single go for reference or comparison. Once a request is submitted successfully, the service would return all the matching geofences in the response along with their details.
Request Parameter
Loading...Request Body
Loading...Example-Get Multiple Geofences
Let’s create a request for searching the geofences created in the Batch Create Geofences example:
Request
1curl --location 'https://api.nextbillion.io/geofence/batch?key=<your_api_key>&ids=test_batch_geofence_1,test_batch_geofence_2,test_batch_geofence_3' \
2--header 'Content-Type: application/json; charset=utf-8'Response
1{
2 "status": "Ok",
3 "data": {
4 "list": [
5 {
6 "id": "test_batch_geofence_1",
7 "name": "Los_Angeles_Downtown_isochrone",
8 "type": "isochrone",
9 "geojson": {
10 "type": "Polygon",
11 "coordinates": [
12 [
13 [
14 -118.222814,
15 34.242702
16 ],
17 [
18 -118.222952,
19 34.240809
20 ],
21 [
22 -118.223961,
23 34.239817
24 ],
25 [
26 -118.224397,
27 34.238253
28 ],
29 [
30 -118.221742,
31 34.241599
32 ],
33 [
34 -118.220809,
35 34.241671
36 ],
37 [
38 -118.222587,
39 34.241898
40 ],
41 [
42 -118.222814,
43 34.242702
44 ]
45 ]
46 ]
47 },
48 "ic_contours_meter": 25000,
49 "ic_coordinates": "34.05067078,-118.24781414",
50 "ic_mode": "car",
51 "ic_denoise": 0.800000011920929,
52 "tags": [
53 "test_tag_1",
54 "test_tag_2"
55 ],
56 "created_at": 1698081817,
57 "updated_at": 1698081823,
58 "meta_data": {}
59 },
60 {
61 "id": "test_batch_geofence_2",
62 "name": "Los_Angeles_Downtown_circle",
63 "type": "circle",
64 "geojson": {
65 "type": "Polygon",
66 "coordinates": [
67 [
68 [
69 -118.246189267,
70 34.050687265
71 ],
72 [
73 -118.246190253,
74 34.050620881
75 ],
76 [
77 -118.246195151,
78 34.050554617
79 ],
80 [
81 -118.246203949,
82 34.050488633
83 ],
84 [
85 -118.246216627,
86 34.050423087
87 ],
88 [
89 -118.246233153,
90 34.050358139
91 ],
92 [
93 -118.246224349,
94 34.050950809
95 ],
96 [
97 -118.246209758,
98 34.05088554
99 ],
100 [
101 -118.246199031,
102 34.050819754
103 ],
104 [
105 -118.246192195,
106 34.050753609
107 ],
108 [
109 -118.246189267,
110 34.050687265
111 ]
112 ]
113 ]
114 },
115 "circle_center": {
116 "lon": -118.24781414,
117 "lat": 34.05067078
118 },
119 "circle_radius": 150,
120 "tags": [
121 "test_tag_2",
122 "test_tag_3"
123 ],
124 "created_at": 1698081817,
125 "updated_at": 1698081817,
126 "meta_data": {}
127 },
128 {
129 "id": "test_batch_geofence_3",
130 "name": "Los_Angeles_Downtown_polygon",
131 "type": "polygon",
132 "geojson": {
133 "type": "Polygon",
134 "coordinates": [
135 [
136 [
137 -118.25192611,
138 34.05493859
139 ],
140 [
141 -118.25672277,
142 34.05083373
143 ],
144 [
145 -118.25688055,
146 34.04518596
147 ],
148 [
149 -118.2533329,
150 34.04268422
151 ],
152 [
153 -118.24779707,
154 34.04266453
155 ],
156 [
157 -118.24525487,
158 34.04565692
159 ],
160 [
161 -118.24363926,
162 34.04929884
163 ],
164 [
165 -118.25192611,
166 34.05493859
167 ]
168 ]
169 ]
170 },
171 "tags": [
172 "test_tag_1",
173 "test_tag_2"
174 ],
175 "created_at": 1698081817,
176 "updated_at": 1698081817,
177 "meta_data": {}
178 }
179 ]
180 }
181}Get Geofence List
Use this method to retrieve multiple geofences using tags as filter by sending a GET request containing the tag(s) as a request parameter. The API returns a list of geofences that are mapped to the specified tag(s), along with their details such as the type of geofence, name, tags, and geographical coordinates defining their boundary. This method can be useful for retrieving information about multiple geofences that are related to a specific use case or tag, making it easier to manage and organize location-based services.
Request Parameter
Loading...Response Schema
Loading...Example-Get Geofence List
Let’s create a request for retrieving a list of geofences with following filters:
-
couple of
tagsto retrieve specific geofences. -
implement pagination by limiting
psto 2 and retrieving results on the first page only.
curl --location --request GET 'https://api.nextbillion.io/geofence/list?key=<your_api_key>&tags=Los_Angeles_Hotels&ps=2&pn=1'1{
2 "status": "Ok",
3 "data": {
4 "list": [
5 {
6 "id": "1287cd61-fc73-48d2-a82f-6bb4eb0d6f69",
7 "name": "Sheraton Grand Los Angeles",
8 "type": "circle",
9 "geojson": {
10 "type": "Polygon",
11 "coordinates": [
12 [
13 [
14 -118.226140484,
15 34.048200454
16 ],
17 [
18 -118.22616052,
19 34.046872766
20 ],
21 [
22 -118.226258792,
23 34.045547496
24 ],
25 [
26 -118.226435061,
27 34.044227836
28 ],
29 [
30 -118.226688898,
31 34.042916964
32 ],
33 [
34 -118.227019689,
35 34.041618039
36 ],
37 [
38 -118.227426632,
39 34.040334189
40 ],
41 [
42 -118.227908745,
43 34.039068507
44 ],
45 [
46 -118.228464862,
47 34.03782404
48 ],
49 [
50 -118.229093642,
51 34.036603786
52 ],
53 [
54 -118.229793567,
55 34.035410683
56 ],
57 [
58 -118.230562949,
59 34.034247605
60 ],
61 [
62 -118.22765298,
63 34.056038776
64 ],
65 [
66 -118.227209086,
67 34.054763424
68 ],
69 [
70 -118.226840923,
71 34.053471478
72 ],
73 [
74 -118.226549376,
75 34.052166051
76 ],
77 [
78 -118.226335143,
79 34.050850289
80 ],
81 [
82 -118.226198738,
83 34.04952736
84 ],
85 [
86 -118.226140484,
87 34.048200454
88 ]
89 ]
90 ]
91 },
92 "circle_center": {
93 "lon": -118.258637,
94 "lat": 34.047872
95 },
96 "circle_radius": 3000,
97 "tags": [
98 "Hotel-Staff",
99 "Free_transportation_service",
100 "Los_Angeles_Hotels",
101 "Sheraton_Hotel"
102 ],
103 "created_at": 1686259599,
104 "updated_at": 1687759531,
105 "meta_data": {
106 "building": "yes",
107 "amenity": "hotel",
108 "building_name": "Sheraton Grand Los Angeles"
109 }
110 },
111 {
112 "id": "2a8f3db4-0398-4e18-9b52-c3a3efef834b",
113 "name": "The Westin Hotel staff transportation",
114 "type": "circle",
115 "geojson": {
116 "type": "Polygon",
117 "coordinates": [
118 [
119 [
120 -118.201070649,
121 34.053340222
122 ],
123 [
124 -118.201104691,
125 34.051127403
126 ],
127 [
128 -118.201269133,
129 34.04891864
130 ],
131 [
132 -118.201563568,
133 34.046719253
134 ],
135 [
136 -118.201987277,
137 34.044534539
138 ],
139 [
140 -118.202539229,
141 34.042369761
142 ],
143 [
144 -118.203218086,
145 34.040230132
146 ],
147 [
148 -118.205438003,
149 34.070552815
150 ],
151 [
152 -118.20445179,
153 34.068497637
154 ],
155 [
156 -118.203587988,
157 34.066404656
158 ],
159 [
160 -118.20284867,
161 34.064278916
162 ],
163 [
164 -118.202235608,
165 34.062125542
166 ],
167 [
168 -118.201750271,
169 34.059949723
170 ],
171 [
172 -118.201393818,
173 34.057756702
174 ],
175 [
176 -118.201167099,
177 34.055551764
178 ],
179 [
180 -118.201070649,
181 34.053340222
182 ]
183 ]
184 ]
185 },
186 "circle_center": {
187 "lon": -118.255235,
188 "lat": 34.052799
189 },
190 "circle_radius": 5000,
191 "tags": [
192 "Hotel-Staff",
193 "Free_transportation_service",
194 "Los_Angeles_Hotels",
195 "Westin_Hotel"
196 ],
197 "created_at": 1686816833,
198 "updated_at": 1687759582,
199 "meta_data": {
200 "building": "yes",
201 "building_name": "The Westin Bonaventure Hotel & Suites, Los Angeles"
202 }
203 }
204 ],
205 "page": {
206 "total": 356,
207 "page": 1,
208 "size": 2,
209 "hasmore": true
210 }
211 }
212 }Update a Geofence
Use this method to update an existing geofence by sending a PUT request containing the ID of the geofence as a path parameter and its properties to be updated in the request body. The updated details may include information such as the type of geofence, its name, tags, and the geographical coordinates defining its boundary. Once the request is processed successfully, the geofence is updated with the new information and can be used for location-based services with the updated details. It's important to note that updating a geofence may have implications for any services or applications that rely on it, so it should be done with care.
Request Parameter
Loading...Request Body
Loading...Response Schema
Loading...Example-Update a Geofence
Let’s update the details of an existing geofence. We will
-
change the
centerof a circular geofence -
modify the
radiusof a circular geofence -
update the
nameof a geofence
Request
1curl --location --request PUT 'https://api.nextbillion.io/geofence/1287cd61-fc73-48d2-a82f-6bb4eb0d6f69?key=<your_api_key>'
2--header 'Content-Type: application/json'
3--data-raw '{
4 "circle": {
5 "center": {
6 "lat":34.047872,
7 "lon":-118.258637
8 },
9 "radius": 3000
10 },
11 "meta_data": {"building":"yes",
12 "amenity":"hotel",
13 "building_name":"Sheraton Grand Los Angeles"},
14 "name": "Sheraton Grand Los Angeles",
15 "tags": [
16 "Hotel-Staff",
17 "Free_transportation_service"
18],
19 "type": "circle"
20}'Response
1{
2"status": "Ok"
3}
4Geofence Contains
Use this method to determine if a specific point is contained in one or more geofences by sending a GET request containing the geofence IDs and the location coordinates as request parameters. After successful processing of the request, the API will return a list of geofences along with a boolean parameter to denote if the provided location coordinate(s) lie within the geofence or not. Please note that the product of the number of geofences and the number locations provided in input determines the matrix size. The maximum matrix size allowed per request is 5000. This method can be useful for location-based services that require checking whether a user's current position is within a specific geofenced area or not, such as delivery services, fleet management, and ride-hailing apps.
Request Parameter
Loading...Response Schema
Loading...Example-Geofence Contains
Let’s create a request to check if some locations belong to a given set of geofences.
Request
curl --location --request GET 'https://api.nextbillion.io//geofence/contain?key=<your_api_key>&geofences=07fe7b57-1255-42ae-99af-44e4e3d2468a,088f8823-9ef0-4029-8ff0-6cddaac25e42&locations=13.25805884388484,77.91083661048299|13.25805884388484,77.91083661048299|17.446580,78.394902&verbose=false'Response
1{
2 "status": "Ok",
3 "data": {
4 "result_list": [
5 {
6 "geofence_id": "07fe7b57-1255-42ae-99af-44e4e3d2468a",
7 "result": [
8 {
9 "contain": false,
10 "location_index": 0
11 },
12 {
13 "contain": false,
14 "location_index": 1
15 },
16 {
17 "contain": true,
18 "location_index": 2
19 }
20 ]
21 },
22 {
23 "geofence_id": "088f8823-9ef0-4029-8ff0-6cddaac25e42",
24 "result": [
25 {
26 "contain": false,
27 "location_index": 0
28 },
29 {
30 "contain": false,
31 "location_index": 1
32 },
33 {
34 "contain": false,
35 "location_index": 2
36 }
37 ]
38 }
39 ]
40 }
41 }Delete a Geofence
Use this method to delete an existing geofence by sending a DELETE request containing the ID of the geofence as a path parameter. It's important to note that deleting a geofence may have implications for any services or applications that rely on it, so it should be done with care.
Request Parameter
Loading...Response Schema
Loading...Example-Delete a Geofence
Following is a sample request to delete a previously created geofence using its ID
Request
curl --location --request DELETE 'https://api.nextbillion.io/geofence/0c3fdb5b-ef38-4e84-abfe-bfebd29ac1a1?key=<your_api_key>'Response
1{
2 "status": "ok"
3}
4Batch Delete Geofence
Use this method to delete geofences in bulk using their IDs by sending a DELETE request containing the array of geofence IDs to be deleted in the request body. This method can be useful for managing and organizing geofences in bulk. It's important to note that deleting a geofences may have implications for any services or applications that rely on it, so it should be done with care.
Request Parameter
Loading...Request Body
Loading...Response Schema
Loading...Example-Batch Delete Geofence
Following is an example of deleting multiple geofences with a single request.
Request
1curl --location --request DELETE 'https://api.nextbillion.io/geofence/batch?key=<your_api_key>'
2--header 'Content-Type: application/json'
3--data-raw '{
4 "ids":["0031d8a1-c4da-4b54-9bb8-ddee765e605f",
5"11af6ddd-c69e-4235-967d-0e68002f58aa"
6]
7}'Response
1{
2 "status": "ok"
3}Namespaces
Namespaces help users to create multiple keys under one parent organization. This feature allows users to share the capabilities of Geofence API with multiple consumers (customers, teams, departments etc) while ensuring isolation of underlying data - a key belonging to a namespace can access the data belonging to that namespace only. However, using namespaces is not mandatory to access the capabilities of Geofence services. Once a request is successfully submitted, the service responds with a unique key for the namespace along with an expiration date for the key.
Please note that once the namespace keys are created, users can manage them through the APIs & Services > Credentials section of their NextBillion Console.
Request Parameter
Loading...Response Schema
Loading...Sample API Request
Let’s create a namespace called sample_namespace for a key represented by <your_api_key>.
curl --location --request POST 'https://namespaces.nextbillion.io/namespaced-apikeys?key=<your_api_key>&namespace=sample_namespace'Sample API Response
1{
2 "kid": "af088b64d85e4c2896034d34383deb8b",
3 "namespace": "sample_namespace",
4 "created_at": "2023-11-21T04:29:15.868Z",
5 "expire": "1716805800"
6}API Query Limits
-
When creating geofences, please ensure the right input parameters are used depending on the value of
type. -
The maximum number of characters in the
meta_dataobject should be such that the overall size of the object is not more than 65Kb. -
When creating a
circletype of geofence, theradiusof the circle should not be more than 50000 m (50 km). -
When creating an
isochronetype of geofence:-
The drive duration i.e. the value of
contours_minutecan be set to a maximum of 40 minutes and the maximum drive distance i.e. the value ofcontours_meteris 60000 meters. -
It is recommended to provide only one of
contours_meterandcontours_minute. If bothcontours_meterandcontours_minuteare provided,contours_meterwill be ignored. An error would be returned if none of them are provided.
-
-
When creating a
polygontype of geofence:-
an open polygon (when the first and the last coordinates are not equal) or a self-intersecting polygon or a polygon containing other polygons should not be provided as input. If provided, then such polygons would be ignored while processing the request.
-
Please ensure that the area of the desired polygon is less than 2000 km2.
-
-
A maximum of 100 geofences can be created using the Batch Create Geofences method.
-
When implementing pagination on the results of Get Geofence List, page size i.e.
pscan be set to a maximum of 100 items per page. -
For
stringtype parameters liketags,geofences,locationsetc the maximum length of input values should not be more than 256 characters. -
For Geofence Contains method, please note the product of the number of geofences and the number locations provided in input determines the matrix size. The maximum matrix size allowed per request is 5000.
-
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.
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 geofence could not be generated for the given combination of parameters. Please check the error message for more details. |
| 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. |
