Subscribing to the Geofencing API

Log in to Network as Code Developer Portal and head over to the Dashboard. Then, click Create and manage organizations and a new window will open, from which you can select API Hub on the top-right menu. Click the top-left search box and just type in the Geofencing API name.

NOTE: Remember to subscribe to the Geofencing API first, after which you will be able to click Test Endpoint and use the API. Here's a step-by-step on how to subscribe to APIs.

The Network as Code Geofencing has four endpoints:

  1. Subscribe to Geofencing notifications for when a device enters, or leaves a given area with the POST createSubscription endpoint.

  2. Unsubscribe from Geofencing notifications using a subscriptionsId with the DELETE deleteSubscription endpoint.

  3. Get a Geofencing subscription by its subscriptionsId with the GET getSubscription endpoint.

  4. Get a list of Geofencing subscriptions by a given access token with the GET getSubscriptionList endpoint

Required API parameters

  • subscriptionsId: The subscription identifier returned when the subscription is created.

    NOTE: This parameter is only required to use the DELETE deleteSubscription and GET getSubscription endpoints.

Subscription request body

Substitute the parameter example values below with the actual details for the device that you want to test or keep track of with geofencing notifications.

{
    "webhook": {
        "notificationUrl": "https://example.com/notify",
        "notificationAuthToken": "replace-with-your-auth-token"
    },
    "subscriptionDetail": {
        "device": {
            "phoneNumber": "36721601234567",
            "networkAccessIdentifier": "device@testcsp.net",
            "ipv4Address": {
                "publicAddress": "233.252.0.2",
                "privateAddress": "192.0.2.25",
                "publicPort": 80
            },
            "ipv6Address": "2001:db8:1234:5678:9abc:def0:fedc:ba98"
        },
        "area": {
            "areaType": "CIRCLE"
        },
        "type": "org.camaraproject.geofencing.v0.area-entered"
    },
    "subscriptionExpireTime": "2024-01-11T11:53:20.293671Z"
}

Subscription request body objects

The main objects in the subscription body include webhook, subscriptionDetails and subscriptionExpireTime. These objects contain other objects and parameters, which are also detailed below them.

NameDescriptionTypeRequired
webhookDefines the URL and authorization for posting notifications.Check object details below.Yes
subscriptionDetailsDefines the details of the subscription, such as device, area, etc.Check object details below.Yes
subscriptionExpireTimeSpecifies when the location-tracking should end.Date-time string in ISO 8601 format, e.g.: 2023-08-20T21:01:02.345Z.No

Webhook

NameDescriptionTypeRequired
notificationUrlCreate or provide an API endpoint (also referred to as callback URL or webhook.)stringYes
notificationAuthTokenAn OAuth2 token or password used to identify the sender of the notification, which must also be indicated within the HTTP Authorization header e.g. Authorization: Bearer $notificationAuthToken.stringNo

Subscription details

NameDescriptionTypeRequired
deviceIt has four fields that allow you to identify a mobile device in different ways: by its ID, phone number, IPv4 address and IPv6 address.Check object details below.Yes
areaWhere you can define the geofenced area.Check object details below.Yes
typeType of event you want to subscribe to: area-entered or area-left, triggered when the device enters or leaves a given area.stringYes

Objects within Subscription Details

  • Device

    NOTE: All the parameters below are OPTIONAL, but at least one must be chosen to identify the device.

    NameDescriptionType
    networkAccessIdentifierThe Device ID can work as an alternate for phone number.string
    phoneNumberPhone-number identifier for devices or users owning the mobile subscription. In E.164 standard, optionally prefixed with '+'.string
    Ipv4AddressFor Network Translation to happen, use either the public (observed) address and port or public address and private (local) address (preferred method).string
    Ipv6AddressUse the seen IPv6 address or any single IPv6 address from the device's allocated subnet, e.g.: adding ::0 to the /64 prefix.string
  • Area

    NameDescriptionTypeRequired
    areaTypeThe geofenced area. Only CIRCLE is used, which is given by coordinates for latitude, longitude and a radius (location query accuracy).stringYes
  • Type

    NameDescriptionTypeRequired
    typeProvide either org.camaraproject.geofencing.v0.area-entered, to track when a device enters an area, or org.camaraproject.geofencing.v0.area-left, for when it leaves.stringYes

Subscription expire time

NameDescriptionTypeRequired
subscriptionExpireTimeA date-time stamp specifying when the location-tracking should end. It must follow RFC 3339 and it must provide the time zone. The recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ, which allows formats, such as 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z.stringNo

Response body objects

The following objects are only returned by the API server in the RESPONSE body, which means you do not need to specify them in the POST request:

NameDescription
subscriptionIdThe subscription ID, which can be used later to unsubscribe from notifications or get a subscription by its ID.
startsAtThe date-time stamp for when the subscription will start.
expiresAtThe date-time stamp for when the subscription will end.

Last updated on May 21, 2024