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.

POST

Create a Geofence

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.

/geofence/create

Parameters

Request Parameters

Request Body

Response Schema

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      }

POST

Delete a Geofence

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.

/geofence/delete

Parameters

Request Parameters

Request Body

Response Schema

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

GET

Get a Geofence

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.

/geofence/get

Parameters

Request Parameters

Response Schema

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

GET

Get Geofence List

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.

/geofence/getlist

Parameters

Request Parameters

Response Schema

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

POST

Update a Geofence

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.

/geofence/update

Parameters

Request Parameters

Request Body

Response Schema

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      }

POST

Delete Batch Geofence

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.

/geofence/deletebatch

Parameters

Request Parameters

Request Body

Response Schema

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

GET

Geofence Contains

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.

/geofence/contain

Parameters

Request Parameters

Response Schema

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.

Live Tracking

Post Trip Route

Geofencing API

Introduction

Query Limits

Generic Limits

API Error Codes

PLATFORM

SOLUTIONS

RESOURCES

COMPANY

UNITED STATES

SINGAPORE