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

POST

https://api.nextbillion.io/geofence?key={your_api_key}


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 center of the circular geofence.

  • define the radius of a circular geofence

  • set the type of the geofence as circle .

  • add meaningful tags, meta_data and name

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl --location --request POST 'https://api.nextbillion.io/geofence?key=<your_api_key>' 
      --header 'Content-Type: application/json' 
      --data-raw '{
      "circle": {
          "center": {
            "lat":34.052799,
            "lon":-118.255235
          },
          "radius": 5000
        },
        "meta_data": {"building":"yes",
                      "building_name":"The Westin Bonaventure Hotel & Suites, Los Angeles"},
        "name": "The Westin Hotel staff transportation",
        "tags": [
          "Hotel-staff",
          "Free_transportation_service"
      ],
        "type": "circle"
      }'

Response

1
2
3
4
5
6
{
  "status": "Ok",
  "data": {
    "id": "1287cd61-fc73-48d2-a82f-6bb4eb0d6f69"
  }
}

Example 2-Create an isochrone Geofence

Let’s create an isochrone type geofence around a hotel’s location. In the request we:

  • set location coordinates which would act as the starting point to determine the isochrone.

  • set contours_minute to determine the driving time and consequently the isochrone boundaries.

  • add a departure_time to set the typical traffic conditions for which isochrone needs to be configured.

  • set the type of the geofence as isochrone.

  • add meaningful tags, meta_data and name

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
curl --location --request POST 'https://api.nextbillion.io/geofence?key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "isochrone": {
      "coordinates":"34.0453,-118.2666",
  "departure_time": 1691407800,
  "mode": "car",
  "denoise": 0.8,
  "contours_minute": 30
  },
  "meta_data": {
    "purpose":"isochrone_example_geofence",
      "area": "Los Angeles"
    },
  "type": "isochrone",
  "tags": [
    "delivery",
    "vehicle"
  ],
  "name": "The Ritz Carlton, Los Angeles isochrone"
}'

Request

1
2
3
4
5
"status": "Ok",
"data": {
"id": "409f7e0e-4cef-461c-84e1-b3715a5610d1"
}
}

Example 3-Create a polygon Geofence

Let’s create an polygon type geofence around a hotel’s location. In the request we:

  • provide geojson details of the polygon that we want to convert into a geofence.

  • set the type of the geofence as polygon.

  • add meaningful tags, meta_data and name

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
curl --location --request POST 'https://api.nextbillion.io/geofence?key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "polygon":{
     "geojson":{
         "type":"Polygon",
         "coordinates":[
             [
                 [
                    -118.268312,
                    34.046253
                 ],
                 [
                    -118.269707,
                    34.045097
                 ],
                 [
                    -118.270963,
                    34.042996
                 ],
                 [
                    -118.266940,
                    34.042149
                 ],
                 [
                    -118.264289,
                    34.044904
                 ],
                 [
                    -118.264661,
                    34.046638
                 ],
                 [
                    -118.266777,
                    34.047255
                 ],
                 [
                    -118.268312,
                    34.046253
                 ]
             ]
         ]
     } 
  },
  "meta_data": {
    "purpose":"plolygon_example_geofence",
      "area": "Los Angeles"
    },
  "type": "polygon",
  "tags": [
    "delivery",
    "vehicle"
  ],
  "name": "The Ritz Carlton, Los Angeles polygon"
}'

Response

1
2
3
4
5
6
{
"status": "Ok",
"data": {
"id": "24760549-e83d-4ba2-82f3-3a3f3459799d"
}
}

Batch Create Geofences

POST

https://api.nextbillion.io/geofence/batch?key={your_api_key}


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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
curl --location 'https://api.nextbillion.io/geofence/batch?key=<your_api_key>'
--header 'Content-Type: application/json; charset=utf-8' 
--data '{
  "geofences": [
    {
      "custom_id": "test_batch_geofence_1",
      "isochrone": {
        "contours_meter": 25000,
        "denoise": 0.8,
        "mode": "car",
        "coordinates": "34.05067078,-118.24781414"
      },
      "tags": [
        "test_tag_1",
        "test_tag_2"
      ],
      "type": "isochrone",
      "name": "Los_Angeles_Downtown_isochrone"
    },
    {
      "custom_id": "test_batch_geofence_2",
      "tags": [
        "test_tag_2",
        "test_tag_3"
      ],
      "circle": {
        "center": {
          "lon": -118.24781414,
          "lat": 34.05067078
        },
        "radius": 150
      },
      "type": "circle",
      "name": "Los_Angeles_Downtown_circle"
    },
    {
      "custom_id": "test_batch_geofence_3",
      "polygon": {
        "geojson": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -118.25192611,
                34.05493859
              ],
              [
                -118.25672277,
                34.05083373
              ],
              [
                -118.25688055,
                34.04518596
              ],
              [
                -118.2533329,
                34.04268422
              ],
              [
                -118.24779707,
                34.04266453
              ],
              [
                -118.24525487,
                34.04565692
              ],
              [
                -118.24363926,
                34.04929884
              ],
              [
                -118.25192611,
                34.05493859
              ]
            ]
          ]
        }
      },
      "tags": [
        "test_tag_1",
        "test_tag_2"
      ],
      "type": "polygon",
      "name": "Los_Angeles_Downtown_polygon"
    }
  ]
}'

Response

1
2
3
4
5
6
7
8
9
10
{
  "status": "Ok",
  "data": {
    "ids": [
      "test_batch_geofence_1",
      "test_batch_geofence_2",
      "test_batch_geofence_3"
    ]
  }
}

Get a Geofence

GET

https://api.nextbillion.io/geofence/{id}?key={your_api_key}


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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
      "status": "Ok",
      "data": {
        "geofence": {
          "id": "0d469774-0c7e-411d-93d0-f1a5a1f3be16",
          "name": "SF-loc1",
          "type": "polygon",
          "geojson": {
            "type": "Polygon",
            "coordinates": [
              [
                [-122.428554017, 37.787002428],
                [-122.428065855, 37.787013027],
                [-122.428151685, 37.787383979],
                [-122.428755182, 37.787275873],
                [-122.428554017, 37.787002428]
              ]
            ]
          },
          "tags": ["source"],
          "created_at": 1684310763,
          "updated_at": 1684310763,
          "meta_data": {
            "country": "USA,San Francisco"
          }
        }
      }
}

Get Multiple Geofences

GET

https://api.nextbillion.io/geofence/batch?key={your_api_key}


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..

Response Schema

Loading..

Example-Get Multiple Geofences

Let’s create a request for searching the geofences created in the Batch Create Geofences example:

Request

1
2
curl --location 'https://api.nextbillion.io/geofence/batch?key=<your_api_key>&ids=test_batch_geofence_1,test_batch_geofence_2,test_batch_geofence_3' \
--header 'Content-Type: application/json; charset=utf-8'

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
{
    "status": "Ok",
    "data": {
        "list": [
            {
                "id": "test_batch_geofence_1",
                "name": "Los_Angeles_Downtown_isochrone",
                "type": "isochrone",
                "geojson": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                -118.222814,
                                34.242702
                            ],
                            [
                                -118.222952,
                                34.240809
                            ],
                            [
                                -118.223961,
                                34.239817
                            ],
                            [
                                -118.224397,
                                34.238253
                            ],
                            [
                                -118.221742,
                                34.241599
                            ],
                            [
                                -118.220809,
                                34.241671
                            ],
                            [
                                -118.222587,
                                34.241898
                            ],
                            [
                                -118.222814,
                                34.242702
                            ]
                        ]
                    ]
                },
                "ic_contours_meter": 25000,
                "ic_coordinates": "34.05067078,-118.24781414",
                "ic_mode": "car",
                "ic_denoise": 0.800000011920929,
                "tags": [
                    "test_tag_1",
                    "test_tag_2"
                ],
                "created_at": 1698081817,
                "updated_at": 1698081823,
                "meta_data": {}
            },
            {
                "id": "test_batch_geofence_2",
                "name": "Los_Angeles_Downtown_circle",
                "type": "circle",
                "geojson": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                -118.246189267,
                                34.050687265
                            ],
                            [
                                -118.246190253,
                                34.050620881
                            ],
                            [
                                -118.246195151,
                                34.050554617
                            ],
                            [
                                -118.246203949,
                                34.050488633
                            ],
                            [
                                -118.246216627,
                                34.050423087
                            ],
                            [
                                -118.246233153,
                                34.050358139
                            ],
                            [
                                -118.246224349,
                                34.050950809
                            ],
                            [
                                -118.246209758,
                                34.05088554
                            ],
                            [
                                -118.246199031,
                                34.050819754
                            ],
                            [
                                -118.246192195,
                                34.050753609
                            ],
                            [
                                -118.246189267,
                                34.050687265
                            ]
                        ]
                    ]
                },
                "circle_center": {
                    "lon": -118.24781414,
                    "lat": 34.05067078
                },
                "circle_radius": 150,
                "tags": [
                    "test_tag_2",
                    "test_tag_3"
                ],
                "created_at": 1698081817,
                "updated_at": 1698081817,
                "meta_data": {}
            },
            {
                "id": "test_batch_geofence_3",
                "name": "Los_Angeles_Downtown_polygon",
                "type": "polygon",
                "geojson": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                -118.25192611,
                                34.05493859
                            ],
                            [
                                -118.25672277,
                                34.05083373
                            ],
                            [
                                -118.25688055,
                                34.04518596
                            ],
                            [
                                -118.2533329,
                                34.04268422
                            ],
                            [
                                -118.24779707,
                                34.04266453
                            ],
                            [
                                -118.24525487,
                                34.04565692
                            ],
                            [
                                -118.24363926,
                                34.04929884
                            ],
                            [
                                -118.25192611,
                                34.05493859
                            ]
                        ]
                    ]
                },
                "tags": [
                    "test_tag_1",
                    "test_tag_2"
                ],
                "created_at": 1698081817,
                "updated_at": 1698081817,
                "meta_data": {}
            }
        ]
    }
}

Get Geofence List

GET

https://api.nextbillion.io/geofence/list?key={your_api_key}


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 tags to retrieve specific geofences.

  • implement pagination by limiting ps to 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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
{
        "status": "Ok",
        "data": {
          "list": [
            {
              "id": "1287cd61-fc73-48d2-a82f-6bb4eb0d6f69",
              "name": "Sheraton Grand Los Angeles",
              "type": "circle",
              "geojson": {
                "type": "Polygon",
                "coordinates": [
                  [
                    [
                      -118.226140484,
                      34.048200454
                    ],
                    [
                      -118.22616052,
                      34.046872766
                    ],
                    [
                      -118.226258792,
                      34.045547496
                    ],
                    [
                      -118.226435061,
                      34.044227836
                    ],
                    [
                      -118.226688898,
                      34.042916964
                    ],
                    [
                      -118.227019689,
                      34.041618039
                    ],
                    [
                      -118.227426632,
                      34.040334189
                    ],
                    [
                      -118.227908745,
                      34.039068507
                    ],
                    [
                      -118.228464862,
                      34.03782404
                    ],
                    [
                      -118.229093642,
                      34.036603786
                    ],
                    [
                      -118.229793567,
                      34.035410683
                    ],
                    [
                      -118.230562949,
                      34.034247605
                    ],
                    [
                      -118.22765298,
                      34.056038776
                    ],
                    [
                      -118.227209086,
                      34.054763424
                    ],
                    [
                      -118.226840923,
                      34.053471478
                    ],
                    [
                      -118.226549376,
                      34.052166051
                    ],
                    [
                      -118.226335143,
                      34.050850289
                    ],
                    [
                      -118.226198738,
                      34.04952736
                    ],
                    [
                      -118.226140484,
                      34.048200454
                    ]
                  ]
                ]
              },
              "circle_center": {
                "lon": -118.258637,
                "lat": 34.047872
              },
              "circle_radius": 3000,
              "tags": [
                "Hotel-Staff",
                "Free_transportation_service",
                "Los_Angeles_Hotels",
                "Sheraton_Hotel"
              ],
              "created_at": 1686259599,
              "updated_at": 1687759531,
              "meta_data": {
                "building": "yes",
                "amenity": "hotel",
                "building_name": "Sheraton Grand Los Angeles"
              }
            },
            {
              "id": "2a8f3db4-0398-4e18-9b52-c3a3efef834b",
              "name": "The Westin Hotel staff transportation",
              "type": "circle",
              "geojson": {
                "type": "Polygon",
                "coordinates": [
                  [
                    [
                      -118.201070649,
                      34.053340222
                    ],
                    [
                      -118.201104691,
                      34.051127403
                    ],
                    [
                      -118.201269133,
                      34.04891864
                    ],
                    [
                      -118.201563568,
                      34.046719253
                    ],
                    [
                      -118.201987277,
                      34.044534539
                    ],
                    [
                      -118.202539229,
                      34.042369761
                    ],
                    [
                      -118.203218086,
                      34.040230132
                    ],
                    [
                      -118.205438003,
                      34.070552815
                    ],
                    [
                      -118.20445179,
                      34.068497637
                    ],
                    [
                      -118.203587988,
                      34.066404656
                    ],
                    [
                      -118.20284867,
                      34.064278916
                    ],
                    [
                      -118.202235608,
                      34.062125542
                    ],
                    [
                      -118.201750271,
                      34.059949723
                    ],
                    [
                      -118.201393818,
                      34.057756702
                    ],
                    [
                      -118.201167099,
                      34.055551764
                    ],
                    [
                      -118.201070649,
                      34.053340222
                    ]
                  ]
                ]
              },
              "circle_center": {
                "lon": -118.255235,
                "lat": 34.052799
              },
              "circle_radius": 5000,
              "tags": [
                "Hotel-Staff",
                "Free_transportation_service",
                "Los_Angeles_Hotels",
                "Westin_Hotel"
              ],
              "created_at": 1686816833,
              "updated_at": 1687759582,
              "meta_data": {
                "building": "yes",
                "building_name": "The Westin Bonaventure Hotel & Suites, Los Angeles"
              }
            }
          ],
          "page": {
            "total": 356,
            "page": 1,
            "size": 2,
            "hasmore": true
          }
        }
      }

Update a Geofence

PUT

https://api.nextbillion.io/geofence/{id}?key={your_api_key}


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 center of a circular geofence

  • modify the radius of a circular geofence

  • update the name of a geofence

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
curl --location --request PUT 'https://api.nextbillion.io/geofence/1287cd61-fc73-48d2-a82f-6bb4eb0d6f69?key=<your_api_key>' 
--header 'Content-Type: application/json' 
--data-raw '{
  "circle": {
    "center": {
      "lat":34.047872,
      "lon":-118.258637
    },
    "radius": 3000
  },
  "meta_data": {"building":"yes",
                "amenity":"hotel",
                "building_name":"Sheraton Grand Los Angeles"},
  "name": "Sheraton Grand Los Angeles",
  "tags": [
    "Hotel-Staff",
    "Free_transportation_service"
],
  "type": "circle"
}'

Response

1
2
3
{
"status": "Ok"
}

Geofence Contains

GET

https://api.nextbillion.io/geofence/contain?key={your_api_key}


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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "status": "Ok",
  "data": {
    "result_list": [
      {
        "geofence_id": "07fe7b57-1255-42ae-99af-44e4e3d2468a",
        "result": [
          {
            "contain": false,
            "location_index": 0
          },
          {
            "contain": false,
            "location_index": 1
          },
          {
            "contain": true,
            "location_index": 2
          }
        ]
      },
      {
        "geofence_id": "088f8823-9ef0-4029-8ff0-6cddaac25e42",
        "result": [
          {
            "contain": false,
            "location_index": 0
          },
          {
            "contain": false,
            "location_index": 1
          },
          {
            "contain": false,
            "location_index": 2
          }
        ]
      }
    ]
  }
  }

Delete a Geofence

DELETE

https://api.nextbillion.io/geofence/{id}?key={your_api_key}


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
3
{
  "status": "ok"
}

Batch Delete Geofence

DELETE

https://api.nextbillion.io/geofence/batch?key={your_api_key}


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

1
2
3
4
5
6
7
curl --location --request DELETE 'https://api.nextbillion.io/geofence/batch?key=<your_api_key>'
--header 'Content-Type: application/json' 
--data-raw '{
    "ids":["0031d8a1-c4da-4b54-9bb8-ddee765e605f",
"11af6ddd-c69e-4235-967d-0e68002f58aa"
]
}'

Response

1
2
3
{
    "status": "ok"
}

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.

POST

https://namespaces.nextbillion.io/namespaced-apikeys?namespace={namespace}&key={your_api_key}

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
3
4
5
6
{
   "kid": "af088b64d85e4c2896034d34383deb8b",
   "namespace": "sample_namespace",
   "created_at": "2023-11-21T04:29:15.868Z",
   "expire": "1716805800"
}

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_data object should be such that the overall size of the object is not more than 65Kb.

  • When creating a circle type of geofence, the radius of the circle should not be more than 50000 m (50 km).

  • When creating an isochrone type of geofence:

    • The drive duration i.e. the value of contours_minute can be set to a maximum of 40 minutes and the maximum drive distance i.e. the value of contours_meter is 60000 meters.

    • It is recommended to provide only one of contours_meter and contours_minute. If both contours_meter and contours_minute are provided, contours_meter will be ignored. An error would be returned if none of them are provided.

  • When creating a polygon type 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. ps can be set to a maximum of 100 items per page.

  • For string type parameters like tags, geofences, locations etc 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 CodeDescriptionAdditional Notes
200Normal success case.

Normal success case.

400Input validation failed.

There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.

401APIKEY not supplied or invalid.

This error occurs when the wrong API key is passed in the request or the key is missing altogether

403APIKEY 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.

404Requested host/path not found.

This error occurs when a malformed hostname is used.

422Could not process the request.

Valid geofence could not be generated for the given combination of parameters. Please check the error message for more details.

429Too many requests.

QPM reached or API request count quota reached.

500Internal Service error.

There was an internal issue with NextBillion.ai services. You can reach out to [email protected] for an explanation.

Have Questions ?

© 2024 NextBillion.ai all rights reserved.

Privacy Policy Terms of ServiceSLASupport Services Agreement