# Natural geocoding

`POST https://bemap.benomad.com/bgis/service/geofencing/1.0`

Part of [Geofencing](https://benomad.com/dev/doc/bemap-api/search/geofencing.md).

> **Check positions against zones.** Whether each position is inside or outside the zones you define, such as a depot, a customer site or a restricted area. Use it to know when a vehicle enters or leaves a site, or to check that a delivery happened where it should.

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

Provisioned per account: without it, BeMap answers `400 Access Denied`.

## Request body

JSON, `Content-Type: application/json`. Schema `GeofencingRequest`.

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

`200`, schema `GeofencingResponse`.

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

## Errors

- `400`: Bad Request
- `302`: no credentials were sent. Do not follow the redirect.
- `401`: the account or the API key is wrong.

How to read each one: [Errors](https://benomad.com/dev/doc/bemap-api/getting-started/errors.md).

## Example

```bash
curl -X POST 'https://bemap.benomad.com/bgis/service/geofencing/1.0' \
  -u 'YOUR_ACCOUNT:YOUR_API_KEY' \
  --fail-with-body \
  -H 'Content-Type: application/json' \
  -d '{
  "positions": [
    {
      "lat": 48.8606,
      "lon": 2.3376
    },
    {
      "lat": 48.8738,
      "lon": 2.295
    }
  ],
  "fenceShapes": [
    {
      "id": 1,
      "type": "CIRCLE",
      "center": {
        "lat": 48.8606,
        "lon": 2.3376
      },
      "radius": 500
    },
    {
      "id": 2,
      "type": "POLYGON",
      "vertices": [
        {
          "lat": 48.87,
          "lon": 2.29
        },
        {
          "lat": 48.878,
          "lon": 2.29
        },
        {
          "lat": 48.878,
          "lon": 2.3
        },
        {
          "lat": 48.87,
          "lon": 2.3
        }
      ]
    }
  ]
}'
```

Response captured from production:

```json
{
  "fenceResults": [
    {
      "id": 1,
      "type": "CIRCLE",
      "positionStates": [
        "INSIDE",
        "OUTSIDE"
      ]
    },
    {
      "id": 2,
      "type": "POLYGON",
      "positionStates": [
        "OUTSIDE",
        "INSIDE"
      ]
    }
  ]
}
```

## Reference pages

- [Geo-fencing service](https://benomad.com/dev/doc/bemap-api/guides/services/geofencing.md)