Geofence API

API Overview

NextBillion.ai's Geofence API is a robust solution that enables users to establish and control custom geographical boundaries, commonly referred to as geofences, on a digital map. With this API, businesses can define areas of interest and use them for meeting various business needs. Businesses involved in providing location-based services, fleet management, asset tracking services, or logistics services can use the Geofence API to improve their operations, enhance customer experiences, and increase efficiency.

With NextBillions's Geofence API, businesses can easily create, modify and delete geofences of three types - circle, custom polygon, or isochrone based geofences on a map. Let’s take a look at the Geofence API’s methods and their properties.

Create a Geofence

Use this method to create a new geofence through a POST request containing the necessary parameters in the request body. The parameters typically include information such as the type of geofence, its name, tags, and the geographical coordinates defining its boundary. Users can create circular, custom polygon or isochrone based geofences. Once the request is processed successfully, the geofence is created and can be used for a variety of location-based services such as geotargeting, asset tracking, and more

Request Parameter

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

1
curl --location --request POST 'https://api.nextbillion.io/geofence?key=<your_api_key>' 
2
      --header 'Content-Type: application/json' 
3
      --data-raw '{...}'

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

1
curl --location --request POST 'https://api.nextbillion.io/geofence?key=<your_api_key>' 
2
      --header 'Content-Type: application/json' 
3
      --data-raw '{...}'

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

1
curl --location --request POST 'https://api.nextbillion.io/geofence?key=<your_api_key>' 
2
      --header 'Content-Type: application/json' 
3
      --data-raw '{...}'

Response

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

Batch Create Geofences

Use this method to create geofences in bulk by sending a POST request containing an array with details of each geofence to be created in the request body. This method is helpful in easily creating up to 100 geofences with only a single request. Users can also provide custom IDs for the geofences or else they can rely on the service to create auto-generated IDs. The service will respond with the IDs of the newly created geofences.

Request Parameter

Request Body

Response Schema

Example-Batch Create Geofence

Let’s create a request for creating one geofences of each type using the following parameters:

Request

1
curl --location 'https://api.nextbillion.io/geofence/batch?key=<your_api_key>'
2
--header 'Content-Type: application/json; charset=utf-8' 
3
--data  '{...}'

Response

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

Get a Geofence

Use this method to find an existing geofence using its ID through a GET request containing the ID of the geofence as a path parameter. Once the request is processed successfully, the API will return the details of the geofence, which typically include information such as the type of geofence, its name, tags, and the geographical coordinates defining its boundary. This method can be useful for retrieving information about a geofence that was previously created and is needed for further processing or analysis.

Request Parameter

Response Schema

Example-Get a Geofence

Let’s retrieve a previously created geofence using its ID.

Request

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

Get Multiple Geofences

Use this method to search and retrieve several geofences using their IDs by sending a GET request containing the list of geofence IDs to be retrieved as a request parameter. This method can be helpful in quickly looking for multiple geofences in a single go for reference or comparison. Once a request is submitted successfully, the service would return all the matching geofences in the response along with their details.

Request Parameter

Response Schema

Example-Get Multiple Geofences

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

Request

1
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' \
2
--header 'Content-Type: application/json; charset=utf-8'

Response

1
{
2
      "status": "Ok",
3
      "data": "{...}"
4
  }

Get Geofence List

Use this method to retrieve multiple geofences using tags as filter by sending a GET request containing the tag(s) as a request parameter. The API returns a list of geofences that are mapped to the specified tag(s), along with their details such as the type of geofence, name, tags, and geographical coordinates defining their boundary. This method can be useful for retrieving information about multiple geofences that are related to a specific use case or tag, making it easier to manage and organize location-based services.

Request Parameter

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.

Request

1
curl --location --request GET 'https://api.nextbillion.io/geofence/list?key=<your_api_key>&tags=Los_Angeles_Hotels&ps=2&pn=1'

Response

1
{
2
      "status": "Ok",
3
      "data": "{...}"
4
  }

Update a Geofence

Use this method to update an existing geofence by sending a PUT request containing the ID of the geofence as a path parameter and its properties to be updated in the request body. The updated details may include information such as the type of geofence, its name, tags, and the geographical coordinates defining its boundary. Once the request is processed successfully, the geofence is updated with the new information and can be used for location-based services with the updated details. It's important to note that updating a geofence may have implications for any services or applications that rely on it, so it should be done with care.

Request Parameter

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

1
curl --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 '{...}'

Response

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

Geofence Contains

Use this method to determine if a specific point is contained in one or more geofences by sending a GET request containing the geofence IDs and the location coordinates as request parameters. After successful processing of the request, the API will return a list of geofences along with a boolean parameter to denote if the provided location coordinate(s) lie within the geofence or not. Please note that the product of the number of geofences and the number locations provided in input determines the matrix size. The maximum matrix size allowed per request is 5000. This method can be useful for location-based services that require checking whether a user's current position is within a specific geofenced area or not, such as delivery services, fleet management, and ride-hailing apps.

Request Parameter

Response Schema

Example-Geofence Contains

Let’s create a request to check if some locations belong to a given set of geofences.

Request

1
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
{"status": "Ok",
2
  "data":"{...}"
3
  }

Delete a Geofence

Use this method to delete an existing geofence by sending a DELETE request containing the ID of the geofence as a path parameter. It's important to note that deleting a geofence may have implications for any services or applications that rely on it, so it should be done with care.

Request Parameter

Response Schema

Example-Delete a Geofence

Following is a sample request to delete a previously created geofence using its ID

Request

1
curl --location --request DELETE 'https://api.nextbillion.io/geofence/0c3fdb5b-ef38-4e84-abfe-bfebd29ac1a1?key=<your_api_key>'

Response

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

Batch Delete Geofence

Use this method to delete geofences in bulk using their IDs by sending a DELETE request containing the array of geofence IDs to be deleted in the request body. This method can be useful for managing and organizing geofences in bulk. It's important to note that deleting a geofences may have implications for any services or applications that rely on it, so it should be done with care.

Request Parameter

Request Body

Response Schema

Example-Batch Delete Geofence

Following is an example of deleting multiple geofences with a single request.

Request

1
curl --location --request DELETE 'https://api.nextbillion.io/geofence/batch?key=<your_api_key>'
2
--header 'Content-Type: application/json' 
3
--data-raw '{...}'

Response

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

Namespaces

Namespaces help users to create multiple keys under one parent organization. This feature allows users to share the capabilities of Geofence API with multiple consumers (customers, teams, departments etc) while ensuring isolation of underlying data - a key belonging to a namespace can access the data belonging to that namespace only. However, using namespaces is not mandatory to access the capabilities of Geofence services. Once a request is successfully submitted, the service responds with a unique key for the namespace along with an expiration date for the key.

Please note that once the namespace keys are created, users can manage them through the APIs & Services > Credentials section of their NextBillion Console.

Request Parameter

Response Schema

Sample API Request

Let’s create a namespace called sample_namespace for a key represented by <your_api_key>.

1
curl --location --request POST 'https://namespaces.nextbillion.io/namespaced-apikeys?key=<your_api_key>&namespace=sample_namespace'

Sample API Response

1
{
2
   "kid": "af088b64d85e4c2896034d34383deb8b",
3
   "namespace": "sample_namespace",
4
   "created_at": "2023-11-21T04:29:15.868Z",
5
   "expire": "1716805800"
6
}

API Query Limits

• When creating geofences, please ensure the right input parameters are used depending on the value of type.

• The maximum number of characters in the meta_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 km².

• 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