Geofencing API
Introduction
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, monitor activity within those boundaries, and trigger actions when people or objects enter or exit the defined areas. This technology is especially useful for location-based marketing, fleet management, asset tracking, and logistics, allowing businesses to improve their operations, enhance customer experiences, and increase efficiency. With the Geofence API, businesses can easily create,modify and remove custom areas and polygons on a map, while effortlessly incorporating this functionality into their own applications through seamless integration.
Use this method to create a new geofence
The "/geofence/create" method is used to create a geofence. This is done by sending 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. 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.
Parameters
Request Parameters
Loading...Request Body
Loading...Response Schema
Loading...Sample Request
1curl --location --request POST 'https://api.nextbillion.io/geofence/create?key=<apikey>' --header 'Content-Type: application/json' --data-raw '{
2 "tags": [
3 "test1",
4 "test2"
5 ],
6 "type": "polygon",
7 "name": "test name",
8 "geojson": {
9 "type": "Polygon",
10 "coordinates": [
11 [
12 [
13 -0.696458312,
14 44.83422694
15 ],
16 [
17 -0.676943801,
18 44.779834938
19 ],
20 [
21 -0.543727395,
22 44.76810215
23 ],
24 [
25 -0.465669352,
26 44.809227116
27 ],
28 [
29 -0.478811777,
30 44.903378946
31 ],
32 [
33 -0.655637141,
34 44.908597254
35 ],
36 [
37 -0.696458312,
38 44.83422694
39 ]
40 ]
41 ]
42 },
43 "meta_data": {
44 "country": "France",
45 "group_id": "ABC123"
46 }
47 }'
Sample API Response
1{
2 "status": "ok",
3 "data": "684fe67e-60e7-458d-a9ab-87f629445230"
4 }
Use this method to delete an existing geofence
The "/geofence/delete" method is used to delete an existing geofence. This is done by sending a POST request containing the ID of the geofence to be deleted in the request body. Once the request is processed successfully, the geofence is removed and can no longer be used for location-based services. 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.
Parameters
Request Parameters
Loading...Request Body
Loading...Response Schema
Loading...Sample Request
1curl --location –request POST 'https://api.nextbillion.io/geofence/delete?key=<apikey>' --header 'Content-Type: application/json' --data '{
2 "data":"076f4a4b-0e3f-4869-b8de-8f5b176b63a2"
3 }
4
Sample API Response
1{
2 "status": "ok"
3 }
4
Use this method to find an existing geofence using its ID
The "/geofence/get" method is used to retrieve the details of an existing geofence. This is done by sending a GET request containing the ID of the geofence as a parameter in the URL. 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.
Parameters
Request Parameters
Loading...Response Schema
Loading...Sample Request
1curl --location --request GET 'https://api.nextbillion.io/geofence/get?key=<apikey>&id=684fe67e-60e7-458d-a9ab-87f629445230'
Sample API Response
1{
2 "status": "ok",
3 "data": {
4 "id": "d369c401-e5aa-4179-a3d9-737a8fd99344",
5 "name": "test name",
6 "type": "polygon",
7 "geojson": {
8 "type": "Polygon",
9 "coordinates": [
10 [
11 [
12 -0.696458312,
13 44.83422694
14 ],
15 [
16 -0.676943801,
17 44.779834938
18 ],
19 [
20 -0.543727395,
21 44.76810215
22 ],
23 [
24 -0.465669352,
25 44.809227116
26 ],
27 [
28 -0.478811777,
29 44.903378946
30 ],
31 [
32 -0.655637141,
33 44.908597254
34 ],
35 [
36 -0.696458312,
37 44.83422694
38 ]
39 ]
40 ]
41 },
42 "tags": [
43 "test1",
44 "test2"
45 ],
46 "created_at": 1676055963,
47 "updated_at": 1676055963,
48 "meta_data": {}
49 }
50 }
51
Use this method to search all your geofences using tags as filters.
The "/geofence/getlist" method is used to retrieve a list of geofences that are mapped to specific tag(s). This is done by sending a GET request specifying the tag(s) as a parameter in the URL. Once the request is processed successfully, the API will return 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.
Parameters
Request Parameters
Loading...Response Schema
Loading...Sample Request
1curl --location –-request GET 'https://api.nextbillion.io/geofence/getlist?key=<api key>&pn=1&ps=5&tags;building=Hotel'
Sample API Response
1
2 {
3 "status": "ok",
4 "data": [
5 {
6 "id": "076f4a4b-0e3f-4869-b8de-8f5b176b63a2",
7 "name": "hotel sitara grand",
8 "type": "circle",
9 "circle_center": {
10 "longitude": 78.462754203,
11 "latitude": 17.400671324
12 },
13 "circle_radius": 1000000,
14 "tags": [
15 "India",
16 "Telangana"
17 ],
18 "created_at": 1678356538,
19 "updated_at": 1678356662,
20 "meta_data": {
21 "India": {
22 "amenity": "hotel"
23 },
24 "building": "yes"
25 }
26 },
27 {
28 "id": "6348ce4a-930e-4a54-a5d1-82a39aae9a56",
29 "name": "sdfs",
30 "type": "polygon",
31 "geojson": {
32 "type": "Polygon",
33 "coordinates": [
34 [
35 [
36 103.786296807,
37 1.296524839
38 ],
39 [
40 103.830070458,
41 1.298241013
42 ],
43 [
44 103.82406231,
45 1.272498286
46 ],
47 [
48 103.797283135,
49 1.267692948
50 ],
51 [
52 103.786296807,
53 1.296524839
54 ]
55 ]
56 ]
57 },
58 "tags": [
59 ""
60 ],
61 "created_at": 1677391774,
62 "updated_at": 1677391774,
63 "meta_data": {
64 "sdf": "sdf"
65 }
66 }
67 ],
68 "page": {
69 "total": 2,
70 "page": 1,
71 "size": 2,
72 "hasmore": false
73 }
74
75}
76
77
Use this method to update an existing geofence
The "/geofence/update" method is used to update an existing geofence. This is done by sending a POST request containing the ID of the geofence to be updated, along with the updated details 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.
Parameters
Request Parameters
Loading...Request Body
Loading...Response Schema
Loading...Sample Request
1curl --location --request POST 'https://api.nextbillion.io/geofence/update?key=<apikey>' --header 'Content-Type: application/json' --data-raw '{
2 "meta_data": {
3 "test2": {
4 "test3": "test3"
5 },
6 "test": "test"
7 },
8 "tags": [
9 "test1",
10 "test2"
11 ],
12 "id": "684fe67e-60e7-458d-a9ab-87f629445230",
13 "type": "polygon",
14 "name": "testtest",
15 "geojson": {
16 "type": "Polygon",
17 "coordinates": [
18 [
19 [
20 -0.696458312,
21 44.83
22 ],
23 [
24 -0.676,
25 44.779
26 ],
27 [
28 -0.5,
29 45
30 ],
31 [
32 -0.45,
33 44.8
34 ],
35 [
36 -0.696458312,
37 44.83
38 ]
39 ]
40 ]
41 }
42 }'
Sample API Response
1{
2 "meta_data": {
3 "test2": {
4 "test3": "test3"
5 },
6 "test": "test"
7 },
8 "tags": [
9 "test1",
10 "test2"
11 ],
12 "id": "684fe67e-60e7-458d-a9ab-87f629445230",
13 "type": "polygon",
14 "name": "testtest",
15 "geojson": {
16 "type": "Polygon",
17 "coordinates": [
18 [
19 [
20 -0.696458312,
21 44.83
22 ],
23 [
24 -0.676,
25 44.779
26 ],
27 [
28 -0.5,
29 45
30 ],
31 [
32 -0.45,
33 44.8
34 ],
35 [
36 -0.696458312,
37 44.83
38 ]
39 ]
40 ]
41 }
42 }
Use this method to delete geofences in bulk using their IDs.
The "/geofence/deletebatch" method is used to delete geofences in bulk. This is done by sending a POST request containing an array of geofence IDs to be deleted in the request body. Once the request is processed successfully, the specified geofences are removed and can no longer be used for location-based services. This method can be useful for managing and organizing geofences in bulk, especially when there is a need to delete multiple geofences at once. 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.
Parameters
Request Parameters
Loading...Request Body
Loading...Response Schema
Loading...Sample Request
1
2 curl --location --request POST 'https://api.nextbillion.io/geofence/deletebatch?key=<apikey>' --header 'Content-Type: application/json' --data-raw '{
3 "ids": [
4 "b61afd3e-60c4-49ea-90ab-59d18b0312c1",
5 "b4bd811f-0b3c-45fe-b21d-518b2ea7d440"
6 ]
7 }
8
Sample API Response
1
2 {
3 "status": "ok"
4 }
5
Use this method to determine if a specific point is contained in one or more geofences.
The "/geofence/contain" method is used to check whether a specific position is contained within a geofence or not. This is done by sending a POST request containing the geofence ID and the position coordinates in the request body. After successful processing of the request, the API will return a list of geofences that contain the input point. If there are no geofences that contain the point, the API will return an empty response. This method can be useful for location-based services that require checking whether a user's current position is within a specific geofenced area, such as delivery services, fleet management, and ride-hailing apps.
Parameters
Request Parameters
Loading...Response Schema
Loading...Sample Request
1curl "https://api.nextbillion.io/geofence/contain?key=plaintesting&verbose=true&geofences=2e86e172-bf5a-462f-8658-1ef55885563f,f1eb8160-b1fc-428b-bbc8-4f985344b2d7&locations=3,4%7C44.84026576088411,-0.5715534948845402"
Sample API Response
1
2 {
3 "status": "Ok",
4 "data": [
5 {
6 "geofence_id": "2e86e172-bf5a-462f-8658-1ef55885563f",
7 "geofence_detail": {
8 "id": "2e86e172-bf5a-462f-8658-1ef55885563f",
9 "name": "The Vintage Palace",
10 "type": "polygon",
11 "geojson": {
12 "type": "Polygon",
13 "coordinates": [
14 [
15 [78.433632337, 17.375860222],
16 [78.434399195, 17.375718154],
17 [78.434349574, 17.37521446],
18 [78.433544375, 17.375399578]
19 ]
20 ]
21 },
22 "tags": ["building=Hotel", "amenity=community_centre"],
23 "created_at": 1678342250,
24 "updated_at": 1678342250,
25 "meta_data": { "country": "India", "group_id": "156" }
26 },
27 "result": [
28 { "contain": false, "location_index": 0 },
29 { "contain": false, "location_index": 1 }
30 ]
31 },
32 {
33 "geofence_id": "f1eb8160-b1fc-428b-bbc8-4f985344b2d7",
34 "geofence_detail": {
35 "id": "f1eb8160-b1fc-428b-bbc8-4f985344b2d7",
36 "type": "circle",
37 "geojson": {
38 "type": "Polygon",
39 "coordinates": [
40 [
41 [4.000287924, 2.999999736],
42 [4.000287564, 2.999985533],
43 [4.000286512, 2.999971365],
44 [4.000284769, 2.999957266],
45 [4.00028234, 2.999943269],
46 [4.000279231, 2.99992941],
47 [4.000275449, 2.999915721],
48 [4.000271004, 2.999902234],
49 [4.000265906, 2.999888983],
50 [4.000260168, 2.999876],
51 [4.000253802, 2.999863315],
52 [4.000246825, 2.99985096],
53 [4.000239254, 2.999838964],
54 [4.000231106, 2.999827355],
55 [4.000222401, 2.999816163],
56 [4.000213161, 2.999805413],
57 [4.000203407, 2.999795133],
58 [4.000193163, 2.999785345],
59 [4.000182454, 2.999776075],
60 [4.000171305, 2.999767345],
61 [4.000159743, 2.999759174],
62 [4.000147797, 2.999751584],
63 [4.000135494, 2.999744593],
64 [4.000122865, 2.999738217],
65 [4.000109941, 2.999732471],
66 [4.000096751, 2.99972737],
67 [4.000083328, 2.999722926],
68 [4.000069705, 2.999719149],
69 [4.000055913, 2.999716049],
70 [4.000041987, 2.999713633],
71 [4.00002796, 2.999711906],
72 [4.000013865, 2.999710874],
73 [3.999999737, 2.999710538],
74 [3.99998561, 2.9997109],
75 [3.999971517, 2.999711958],
76 [3.999957493, 2.99971371],
77 [3.999943571, 2.999716152],
78 [3.999929785, 2.999719277],
79 [3.999916168, 2.999723079],
80 [3.999902754, 2.999727548],
81 [3.999889573, 2.999732673],
82 [3.999876659, 2.999738443],
83 [3.999864042, 2.999744842],
84 [3.999851752, 2.999751856],
85 [3.999839819, 2.999759468],
86 [3.999828273, 2.99976766],
87 [3.99981714, 2.999776411],
88 [3.999806447, 2.999785701],
89 [3.999796221, 2.999795507],
90 [3.999786486, 2.999805805],
91 [3.999777265, 2.999816572],
92 [3.999768581, 2.99982778],
93 [3.999760454, 2.999839404],
94 [3.999752904, 2.999851414],
95 [3.99974595, 2.999863782],
96 [3.999739608, 2.999876478],
97 [3.999733892, 2.999889472],
98 [3.999728818, 2.999902732],
99 [3.999724398, 2.999916227],
100 [3.999720641, 2.999929923],
101 [3.999717557, 2.999943788],
102 [3.999715154, 2.999957789],
103 [3.999713437, 2.999971891],
104 [3.99971241, 2.999986061],
105 [3.999712076, 3.000000264],
106 [3.999712436, 3.000014467],
107 [3.999713488, 3.000028635],
108 [3.999715231, 3.000042734],
109 [3.99971766, 3.00005673],
110 [3.999720769, 3.00007059],
111 [3.99972455, 3.000084279],
112 [3.999728996, 3.000097766],
113 [3.999734094, 3.000111016],
114 [3.999739832, 3.000124],
115 [3.999746198, 3.000136684],
116 [3.999753175, 3.00014904],
117 [3.999760746, 3.000161036],
118 [3.999768894, 3.000172645],
119 [3.999777599, 3.000183837],
120 [3.999786839, 3.000194587],
121 [3.999796593, 3.000204867],
122 [3.999806837, 3.000214655],
123 [3.999817546, 3.000223925],
124 [3.999828695, 3.000232655],
125 [3.999840257, 3.000240826],
126 [3.999852203, 3.000248416],
127 [3.999864506, 3.000255407],
128 [3.999877134, 3.000261783],
129 [3.999890059, 3.000267529],
130 [3.999903249, 3.00027263],
131 [3.999916672, 3.000277074],
132 [3.999930295, 3.000280851],
133 [3.999944087, 3.000283951],
134 [3.999958013, 3.000286368],
135 [3.99997204, 3.000288094],
136 [3.999986135, 3.000289126],
137 [4.000000263, 3.000289462],
138 [4.00001439, 3.0002891],
139 [4.000028483, 3.000288042],
140 [4.000042507, 3.00028629],
141 [4.000056429, 3.000283848],
142 [4.000070215, 3.000280723],
143 [4.000083832, 3.000276921],
144 [4.000097246, 3.000272452],
145 [4.000110427, 3.000267327],
146 [4.000123341, 3.000261557],
147 [4.000135958, 3.000255158],
148 [4.000148248, 3.000248144],
149 [4.000160181, 3.000240532],
150 [4.000171727, 3.00023234],
151 [4.00018286, 3.000223589],
152 [4.000193553, 3.000214299],
153 [4.000203779, 3.000204493],
154 [4.000213514, 3.000194195],
155 [4.000222735, 3.000183428],
156 [4.000231419, 3.00017222],
157 [4.000239546, 3.000160596],
158 [4.000247096, 3.000148586],
159 [4.00025405, 3.000136218],
160 [4.000260392, 3.000123522],
161 [4.000266108, 3.000110528],
162 [4.000271182, 3.000097268],
163 [4.000275602, 3.000083773],
164 [4.000279359, 3.000070077],
165 [4.000282443, 3.000056212],
166 [4.000284846, 3.000042211],
167 [4.000286563, 3.000028109],
168 [4.00028759, 3.000013939],
169 [4.000287924, 2.999999736]
170 ]
171 ]
172 },
173 "circle_center": { "longitude": 4, "latitude": 3 },
174 "circle_radius": 32,
175 "tags": ["lxx"],
176 "created_at": 1676873519,
177 "updated_at": 1676873519,
178 "meta_data": {}
179 },
180 "result": [
181 { "contain": true, "location_index": 0 },
182 { "contain": false, "location_index": 1 }
183 ]
184 }
185 ]
186 }
187
Query Limits
Generic 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.
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. | - |
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. |