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

Request URL: POST https://api.nextbillion.io/geofence?{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

Request Body

Response Schema

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

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

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

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}

Get a Geofence

Request URL: GET https://api.nextbillion.io/geofence/{id}?{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

Response Schema

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}

Update a Geofence

Request URL: PUT https://api.nextbillion.io/geofence/{id}?{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

Request Body

Response Schema

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

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}
4

Geofence Contains

Request URL: GET https://api.nextbillion.io/geofence/contain?{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. 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

Response Schema

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

Request URL: DELETE https://api.nextbillion.io/geofence/{id}?{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

Response Schema

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}
4

Get Geofence List

Request URL: https://api.nextbillion.io/geofence/list?{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

Response Schema

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        "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      }

Delete Batch Geofence

Request URL: https://api.nextbillion.io/geofence/batch?{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

Request Body

Response Schema

Example-Delete Batch 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}

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:
1. 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.
2. 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:
1. 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.
2. Please ensure that the area of the desired polygon is less than 2000 km².
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.
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.

Live Tracking

Post Trip Route

Geofence API

API Overview

Create a Geofence

Request Parameter

Request Body

Response Schema

Example 1-Create a circle Geofence

Request

Response

Example 2-Create an isochrone Geofence

Request

Request

Example 3-Create a polygon Geofence

Request

Response

Get a Geofence

Request Parameter

Response Schema

Example-Get a Geofence

Request

Response

Update a Geofence

Request Parameter

Request Body

Response Schema

Example-Update a Geofence

Request

Response

Geofence Contains

Request Parameter

Response Schema

Example-Geofence Contains

Request

Response

Delete a Geofence

Request Parameter

Response Schema

Example-Delete a Geofence

Request

Response

Get Geofence List

Request Parameter

Response Schema

Example-Get Geofence List

Delete Batch Geofence

Request Parameter

Request Body

Response Schema

Example-Delete Batch Geofence

Request

Response

API Query Limits

API Error Codes

PLATFORM

SOLUTIONS

RESOURCES

COMPANY

UNITED STATES

SINGAPORE