# Geo-fencing service

> API reference: [`POST /geofencing/1.0`](https://benomad.com/dev/doc/bemap-api/api/map-context/geofencing.md)

<span class="float-right shadow"><img src="https://benomad.com/dev/doc/bemap-api/guides/images/geofencing-bnd-fences_on_map.png" alt="Fences on map" width="300"></span>

<p class="eyebrow">REST API, Service version 1.0.0</p>

# Geo-fencing service

A geo-fence is a virtual perimeter for a real-world geographic area. A geo-fence could be dynamically generated-as in a radius around a point location, or a geo-fence can be a predefined set of boundaries (such as school zones or neighborhood boundaries).

_For more details: [Wikipedia](https://en.wikipedia.org/wiki/Geo-fence)_

## Summary
1. Request
 1. Mandatory parameters
 2. Optional parameters
2. Response
 1. Details of fields
 2. Response samples

## Request
The request must be sent with the HTTP method `POST` and the HTTP header `Content-Type` set to `application/json`. 

Sample:
URI: `/bgis/service/geofencing/1.0`

POST data:
```javascript
{
    "fenceShapes": [
        {
            "id": "1",
            "type": "CIRCLE",
            "center": {
                "lon": 7.42806,
                "lat": 43.75272
            },
            "radius": 3000
        }
    ],
    "positionType": "POLYGON",
    "positions": [
        {
            "lon": 7.41888,
            "lat": 43.73252
        },
        {
            "lon": 7.41806,
            "lat": 43.73272
        },
        {
            "lon": 7.41537,
            "lat": 43.73169
        },
        {
            "lon": 7.41516,
            "lat": 43.73184
        },
        {
            "lon": 7.41461,
            "lat": 43.73224
        }
    ]
}
```

All coordinates are defined by longitude and latitude, see the [coordinate system](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md) glossary for more details.

### __Parameters__

- `fenceShapes` (GeoFenceShp[], required): Define a fence shape to perform a intersection test between the route and fence.
  - `center` (Coordinate, required): Center of circle fence.
    - `lon` (number (double), required): Longitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `longitude`.
    - `lat` (number (double), required): Latitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `latitude`.
  - `radius` (integer (int64), required): Radius of circle fence.
  - `vertices` (Coordinate[], required): Vertices of polygon fence.
    - `lon` (number (double), required): Longitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `longitude`.
    - `lat` (number (double), required): Latitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `latitude`.
  - `id` (integer (int64)): The fence id. If value is negative the server will set it with an auto-incrementing number.
  - `type` (enum): Define the type of geometric shape of fence, like CIRCLE or POLYGON.
    - `CIRCLE`: Circle.
    - `POLYGON`: Polygon.
- `positions` (GeofencingPos[], required): The coordinates will be compared with the fences.
  - `lon` (number (double), required): Longitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `longitude`.
  - `lat` (number (double), required): Latitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `latitude`.
  - `radius` (integer (int64)): Radius in meters.
- `geoserver` (string): Geoserver name.
- `swidx` (integer (int32), deprecated): Switch index.
- `positionType` (enum): Define type of `positions` parameter used to perform a comparison between fence shapes and coordinates.
  - `CIRCLE`: Define type of xy parameter as circle to perform a comparison between fence shapes and a circle.
  - `POLYLINE`: Define the interpretation of coordinates of xy parameter to perform a comparison between fence shapes and a polyline.
  - `POLYGON`: Define the interpretation of coordinates of xy parameter to perform a comparison between fence shapes and a polygon.
- `options` (enum[]): Comma-separated list of one or more geo-fencing options.
  - `SEARCH`: Enable to search the fences with coordinate, in this case the parameter `positions` can be use the radius.

## Response
Return a list in same order of xy parameters (list of coordinates) with state INSIDE, OUTSIDE or INTERSECT.

### Result of compare test
* positionStates: The status of result. Available values below.

| Values     | Illustration | Description |
|:----------:|:------------:|-------------|
| `INSIDE` | <img src="https://benomad.com/dev/doc/bemap-api/guides/images/geofencing-bnd-inside.svg" alt="inside" width="164"> | Defines if the tested coordinate is in fence. |
| `OUTSIDE`    | <img src="https://benomad.com/dev/doc/bemap-api/guides/images/geofencing-bnd-outside.svg" alt="outside" width="164"> | Defines if the tested coordinate is out of fence. |
| `INTERSECT` | <img src="https://benomad.com/dev/doc/bemap-api/guides/images/geofencing-bnd-intersect.svg" alt="intersect" width="164"> | Position is not completely inside or outside but the shapes are intersected. |

### Details of fields

- `fenceResults` (GeofencingRes[]): Return a list in same order of xy parameters (list of coordinates) with state INSIDE, OUTSIDE or INTERSECT.
  - `id` (integer (int64)): Unique ID of fence.
  - `type` (enum): Type of geometry.
    - `CIRCLE`: Circle.
    - `POLYGON`: Polygon.
  - `fenceShape` (GeoFenceShp): Shape of fence used to perform the test.
    - `center` (Coordinate, required): Center of circle fence.
      - `lon` (number (double), required): Longitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `longitude`.
      - `lat` (number (double), required): Latitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `latitude`.
    - `radius` (integer (int64), required): Radius of circle fence.
    - `vertices` (Coordinate[], required): Vertices of polygon fence.
      - `lon` (number (double), required): Longitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `longitude`.
      - `lat` (number (double), required): Latitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `latitude`.
    - `id` (integer (int64)): The fence id. If value is negative the server will set it with an auto-incrementing number.
    - `type` (enum): Define the type of geometric shape of fence, like CIRCLE or POLYGON.
      - `CIRCLE`: Circle.
      - `POLYGON`: Polygon.
  - `positionStates` (enum[]): Defines position state of tested coordinate on the fence geometry.
    - `INWARD`: Defines if the tested coordinate is an inward intersection.
    - `INSIDE`: Defines if the tested coordinate is in fence.
    - `OUTWARD`: Defines if the tested coordinate is an outward intersection.
    - `OUTSIDE`: Defines if the tested coordinate is out of fence.
    - `INTERSECT`: Position is not completely inside or outside but the shapes are intersected.

### Response samples

JSON Sample:
```javascript
{
    "fenceResults": [
        {
            "id": 1,
            "type": "CIRCLE",
            "positionStates": [
                "OUTSIDE"
            ]
        }
    ]
}
```