Areas

An area represents a geographic zone determined by a geojson or a devices group. This concept allows to know the devices inside a concrete area.

If you know the geojson, you can create the area with this information and you can or not add the devices group. By other hand, if you do not know the geojson, you can create the area only with the information of devices group without necesity of its location.

Area object structure

Table 1. area objects and attributes
Object / attribute	Description
identifier	Identifier of the area. This field can be included in the creation option and if it is not included it will automatically assign a uuid.
name	Name of the area. This field is optional.
description	Description of the area. This field is optional.
geometry	Geojson. It contains a type and coordenates of the area. The area supports the following geometry types: Point, Polygon and MultiPolygon
entities	Array of identifiers of entities that defining an area.

The geometry type Point is used when you don’t have the GPS coordenates for a device, but you know the place where it is. This place has a coordenate and it would be the value of this geometry type (point)

Creating an area

POST /north/v80/provision/organizations/{organizationName}/areas

New areas can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.

Let’s show firt two types of json in function how is determined the geographic zone by a geojson or a devices group. Next, the possibility to have information both of them (geojson and devices group).

Area determinated by a devices group as JSON object

{
  "identifier": "Id",
  "name": "area name",
  "description": "description",
  "geometry": {},
  "entities": [
    "identifier1"
  ]
}

Area determinated by a geojson as JSON object

{
  "identifier": "id",
  "name": "area name",
  "description": "description",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          2.173200845718384,
          41.36735636905808
        ],
        [
          2.179992198944092,
          41.364771670743316
        ],
        [
          2.1802926063537598,
          41.36514206995068
        ],
        [
          2.1783506870269775,
          41.36581039362086
        ],
        [
          2.175893783569336,
          41.36669611320903
        ],
        [
          2.1749818325042725,
          41.36675247677479
        ],
        [
          2.174273729324341,
          41.36718727978374
        ],
        [
          2.173200845718384,
          41.36735636905808
        ]
      ]
    ]
  }
}

The polygon must have the first point and the last one equal. That’s how it’s closed

Area determinated by a geojson and a devices group as JSON object

{
  "identifier": "Id",
  "name": "area name",
  "description": "description",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          2.173200845718384,
          41.36735636905808
        ],
        [
          2.179992198944092,
          41.364771670743316
        ],
        [
          2.1802926063537598,
          41.36514206995068
        ],
        [
          2.1783506870269775,
          41.36581039362086
        ],
        [
          2.175893783569336,
          41.36669611320903
        ],
        [
          2.1749818325042725,
          41.36675247677479
        ],
        [
          2.174273729324341,
          41.36718727978374
        ],
        [
          2.173200845718384,
          41.36735636905808
        ]
      ]
    ]
  },
  "entities": [
    "identifier1"
  ]
}

This is the request using curl:

curl --request POST \
     --data-binary @area.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas \
     -H "Content-type: application/json"

In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created area. Let’s look the response.

HTTP/1.1 201 Created
Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas/area_1

Reading an area

GET /north/v80/provision/organizations/{organizationName}/areas/{identifier}

You can apply for the area sending a GET request using the URL above. You must replace {identifier} with the identifier of the area you want to retrieve. This is the request using curl:

curl --request GET \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas/{identifier}

The response body could be something like this:

Response of area

{
  "organization": "organization_area",
  "identifier": "Id",
  "name": "area name",
  "description": "description",
  "geometry": {},
  "entities": [
    "identifier1"
  ]
}

Updating an area

PUT /north/v80/provision/organizations/{organizationName}/areas/{identifier}

It is allowed updating all the fields except the identifier

This is the request using curl:

curl --request PUT \
     --data-binary @area.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas/{identifier} \
     -H "Content-type: application/json"

Deleting an area

DELETE /north/v80/provision/organizations/{organizationName}/areas/{identifier}

You can delete areas by sending a DELETE request using the URL above. You must replace {identifier} with the identifier of the area you want to delete. This is the request using curl.

curl --request DELETE \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/areas/{identifier}