# Near POI

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

Part of [Near POI](https://benomad.com/dev/doc/bemap-api/search/near-poi.md).

> **Find places nearby.** The points of interest around a position, such as fuel stations, restaurants or car parks, limited by the distance to travel to them.

Find POI around a coordinate, limited by distance of travel from coordinate to POI.

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

## Request body

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

- `coordinate` (CoordinateSat, required): Coordinate of center of research, will be used with `distance` parameter.
  - `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`.
  - `heading` (number (double)): Heading in degrees.
  - `speed` (number (float)): Speed in km/h.
  - `time` (integer (int64)): GPS time in milliseconds (EPOCH).
  - `sat` (integer (int32)): Number of GPS satellites available.
- `distance` (integer (int64), required): Limit of research in meters.
- `geoserver` (string): Geoserver name.
- `swidx` (integer (int32), deprecated): Switch index.
- `transportType` (enum): Define the transportation mode: Car, pedestrian, truck, etc. By default PEDESTRIAN.
  - `PEDESTRIAN`: Pedestrian.
  - `BICYCLE`: Bicycle.
  - `MOTORCYCLE`: Motorcycle.
  - `CAR`: Passenger car.
  - `TAXI`: Taxi.
  - `PUBLIC_BUS`: Public bus.
  - `EMERGENCY`: Emergency vehicle.
  - `DELIVERY_TRUCK`: Delivery truck. Deprecated, use `TRUCK` instead.
  - `TRUCK`: Truck.
- `orderBy` (enum): Sort the result by distance or duration in either ascending or descending. Disable by default.
  - `DISTANCE_ASC`: Sort by distance in either ascending.
  - `DISTANCE_DESC`: Sort by distance in either descending.
  - `DURATION_ASC`: Sort by duration in either ascending.
  - `DURATION_DESC`: Sort by duration in either descending.
- `pl` (boolean): Enable the output polyline geometry of route. Set to true to enable otherwise false. Disable by default.
- `epl` (boolean): Enable the output encoded polyline geometry of route with Google Algorithm. Set to true to enable otherwise false. Disable by default.
- `serviceCategories` (string[]): Service categories. POI Class ID (numeric value defining the type of service, see the `Class ID list` in Glossary menu).

## Response

`200`, schema `NearPoiResponse`.

- `pois` (NearPoint[]): Points of interests.
  - `coordinate` (Coordinate): Geographical coordinate of POI.
    - `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`.
  - `distance` (integer (int64)): Distance of travel in meters between the input coordinate and POI.
  - `duration` (integer (int64)): Duration of travel in seconds between the input coordinate and POI.
  - `type` (string): Type of POI.
  - `name` (string): Name of POI.
  - `telephone` (string): Phone number of POI.
  - `comment` (string): Comment.
  - `polyline` (CoordinateFullName[]): Polyline geometry of route between start coordinate and the POI.
    - `longitude` (number (double), required): Longitude in degrees decimal (WGS84) (double).
    - `latitude` (number (double), required): Latitude in degrees decimal (WGS84) (double).
    - `altitude` (number (double)): Altitude in meters.
  - `encodedPolyline` (string): Polyline geometry of route between start coordinate and the POI. It is a composed of coordinates list and encoded with Google Algorithm.

## 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/nearpoi/1.0' \
  -u 'YOUR_ACCOUNT:YOUR_API_KEY' \
  --fail-with-body \
  -H 'Content-Type: application/json' \
  -d '{
  "coordinate": {
    "lat": 48.8606,
    "lon": 2.3376
  },
  "distance": 1000,
  "transportType": "CAR",
  "orderBy": "DISTANCE_ASC"
}'
```

Response captured from production, long arrays and strings shortened:

```json
{
  "pois": [
    {
      "coordinate": {
        "lon": 2.33623,
        "lat": 48.86105
      },
      "distance": 112,
      "duration": 20,
      "type": "THEATRE",
      "name": "Auditorium du Louvre",
      "telephone": "+(33)-1-40205455"
    },
    {
      "coordinate": {
        "lon": 2.33644,
        "lat": 48.86238
      },
      "distance": 164,
      "duration": 31,
      "type": "COMMUTER_RAIL_STATION",
      "name": "Métro-Palais Royal Musée du Louvre",
      "telephone": ""
    }
  ]
}
```

## Reference pages

- [Near POI](https://benomad.com/dev/doc/bemap-api/guides/services/nearpoi.md)