swagger: "2.0"
tags:
- name: "Pois"
  description: "Obtain POIs of an area"
info:
  version: "0.2"
  title: "Openpoiservice"
  contact:
    email: "support@openrouteservice.org"
  license:
    name: "MIT"
    url: "https://github.com/GIScience/openpoiservice/blob/master/LICENSE"
consumes:
- "application/json"
schemes:
- "https"
produces:
- "application/json"
host: "api.openrouteservice.org"
security:
- UserSecurity: [api_key]
paths:
  "/pois":
    post:
      tags:
      - "Pois"
      summary: "Pois Service"
      description: |
        Returns points of interest in the area surrounding a geometry which can either be a bounding box, polygon or buffered linestring or point.
        Find more examples on [github](https://github.com/GIScience/openpoiservice).
      parameters:
      - name: "Authorization"
        in: "header"
        description: |
          Insert your API Key here.
        type: "string"
        required: true
        default: "your-api-key"
      - name: "body"
        in: body
        required: true
#        requiredParams:
#        - request
#        - geometry
        description: body for a post request
        default: '{"request":"pois","geometry":{"bbox":[[8.8034,53.0756],[8.7834,53.0456]],"geojson":{"type":"Point","coordinates":[8.8034,53.0756]},"buffer":250}}'
#        example: {
#          "request": "pois",
#          "geometry": {
#            "bbox": [
#            [8.458614349365236, 55.470054514892844],
#            [8.473613262176515, 55.47323501110393]
#            ],
#            "geojson": {
#              "type": "Point",
#              "coordinates": [8.458614349365236, 55.470054514892844]
#            },
#            "buffer": 100
#          },
#          "limit": 200
#        }
        type: object
        example: '{"request":"pois","geometry":{"bbox":[[8.8034,53.0756],[8.7834,53.0456]],"geojson":{"type":"Point","coordinates":[8.8034,53.0756]},"buffer":250}}'
        props:
          $ref: '#/definitions/LocationsBodyPoisProps'
          # this does not work yet..
          # https://swagger.io/docs/specification/describing-request-body/
          # oneOf:
          #- $ref: '#/definitions/LocationsBodyPois'
          #- $ref: '#/definitions/LocationsBodyStats'
          #- $ref: '#/definitions/LocationsBodyList'
      responses:
        200:
          description: "Standard response for successfully processed requests."
          schema:
            $ref: '#/definitions/LocationsPoiResponse'
            # oneOf:
            #- $ref: '#/definitions/LocationsPoiResponse'
            #- $ref: '#/definitions/LocationsStatsResponse'
            #- $ref: '#/definitions/LocationsListResponse'
        400:
          description: |
            The request was invalid, and more detailed internal errorcode is provided.
            | Internal Code | Description                                        |
            |:-------------:|----------------------------------------------------|
            | 4000 |  Invalid JSON object in request |
            | 4001 |  Category or category group ids missing |
            | 4002 |  Geometry is missing |
            | 4003 |  Bounding box and or geojson not present in request |
            | 4004 |  Buffer is missing |
            | 4005 |  Geometry length does not meet the restrictions |
            | 4006 |  Unsupported HTTP method |
            | 4007 |  GeoJSON parsing error |
            | 4008 |  Geometry size does not meet the restrictions |
            | 4009 |  Unsupported Content-Type |
        401:
          description: "Authorization field missing."
        403:
          description: "Key not authorised."
        500:
          description: "Unknown internal error"
securityDefinitions:
  UserSecurity:
    name: "api_key"
    description: |
      Add your API Key in the header Authorization field.
    type: "apiKey"
    in: "header"
definitions:
  LocationsBodyPoisProps:
    request:
      description: |
        Examples:
        ```
        #### JSON bodies for POST requests
        ##### Pois around a buffered point
        {
          "request": "pois",
          "geometry": {
            "bbox": [
              [8.8034, 53.0756],
              [8.7834, 53.0456]
            ],
            "geojson": {
              "type": "Point",
              "coordinates": [8.8034, 53.0756]
            },
            "buffer": 250
          }
        }

        ##### Pois given categories
        {
          "request": "pois",
          "geometry": {
            "bbox": [
              [8.8034, 53.0756],
              [8.7834, 53.0456]
            ],
            "geojson": {
              "type": "Point",
              "coordinates": [8.8034, 53.0756]
            },
            "buffer": 100
          },
          "limit": 200,
          "filters": {
            "category_ids": [180, 245]
          }
        }

        ##### Pois given category groups
        {
          "request": "pois",
          "geometry": {
            "bbox": [
              [8.8034, 53.0756],
              [8.7834, 53.0456]
            ],
            "geojson": {
              "type": "Point",
              "coordinates": [8.8034, 53.0756]
            },
            "buffer": 100
          },
          "limit": 200,
          "filters": {
            "category_group_ids": [160]
          }
        }

        ##### Pois statistics
        {
          "request": "stats",
          "geometry": {
            "bbox": [
              [8.8034, 53.0756],
              [8.7834, 53.0456]
            ],
            "geojson": {
              "type": "Point",
              "coordinates": [8.8034, 53.0756]
            },
            "buffer": 100
          }
        }

        ##### Pois categories as a list
        {
            "request": "list"
        }
        ```
      type: string
      enum: ['pois', 'stats', 'list']
      example: pois
      required: true
    geometry:
      # 'default' is used instead of 'example' and 'required: true':
      # if 'list' is selected the parameter would be disabled and still be required
      # which is currently not supported in the API playground request validation
      default: '{"bbox":[[8.8034,53.0756],[8.7834,53.0456]],"geojson":{"type":"Point","coordinates":[8.8034,53.0756]},"buffer":200}'
      type: object
      description: "The geometry object which is a geojson or a bounding box object, optionally buffered."
      properties:
        buffer:
          $ref: "#/definitions/buffer"
        bbox:
          $ref: "#/definitions/bbox"
        geojson:
          $ref: "#/definitions/geojson"
      validWhen:
      - ref: 'body.props.request'
        valueNot: 'list'
    filters:
      type: object
      example: '{"fee":"no"}'
      description: "Filters in terms of osm_tags which should be applied to the query."
      properties:
        category_group_ids:
          $ref: "#/definitions/category_group_ids"
        category_ids:
          $ref: "#/definitions/category_ids"
        # CUSTOM FILTERS
        name:
          $ref: "#/definitions/name"
        wheelchair:
          $ref: "#/definitions/wheelchair"
        smoking:
          $ref: "#/definitions/smoking"
        fee:
          $ref: "#/definitions/fee"
      validWhen:
      - ref: 'body.props.request'
        value: 'pois'
    limit:
      description: "The limit of objects to be returned in the response."
      $ref: "#/definitions/limit"
    sortby:
      description: "Either you can sort by category or the distance to the geometry object provided in the request."
      $ref: "#/definitions/sortby"
    title:  "Openpoiservice poi request"

  LocationsBodyStats:
    required:
    - request
    - geometry
    properties:
      request:
        type: string
        example: stats
      geometry:
        type: object
        properties:
          buffer:
            $ref: "#/definitions/buffer"
          bbox:
            $ref: "#/definitions/bbox"
          geojson:
            $ref: "#/definitions/geojson"
      filters:
        type: object
        properties:
          category_group_ids:
            $ref: "#/definitions/category_group_ids"
          category_ids:
            $ref: "#/definitions/category_ids"
          # CUSTOM FILTERS NOT SUPPORTED YET!
          #name:
          #  $ref: "#/definitions/name"
          #wheelchair:
          #  $ref: "#/definitions/wheelchair"
          #smoking:
          #  $ref: "#/definitions/smoking"
          #fee:
          #  $ref: "#/definitions/fee"
    title:  "Openpoiservice category statistics"

  LocationsBodyList:
    required:
    - request
    properties:
      request:
        type: string
        example: list
    title: "Openpoiservice category list"

  # SHARED PROPERTIES
  category_group_ids:
    type: array
    items:
      type: integer
      format: int64
    example: [420]
  category_ids:
    type: array
    items:
      type: integer
      format: int64
    example: [601, 280]
  limit:
    validWhen:
    - ref: 'body.props.request'
      value: 'pois'
    type: integer
    format: int64
    example: 1000
  buffer:
    type: integer
    format: int64
    example: 500
  sortby:
    type: string
    example: category
    enum:
    - category
    - distance
    validWhen:
    - ref: 'body.props.request'
      value: 'pois'
  bbox:
    type: array
    #items:
    #  type: array
    #  minItems: 2
    #  maxItems: 2
    #  items:
    #    type: float
    minItems: 2
    maxItems: 2
    example: [[53.075051,8.798952],[53.080785,8.907160]]
    description: The pattern for this bbox string is minlon,minlat,maxlon,maxlat

  geojson:
    description: This is a GeoJSON object. Is either Point, Polygon or LineString.
    type: object
  # SHARED CUSTOM PROPERTIES
  name:
    description: Filter by name of the poi object.
    type: array
    example: ["Gas station",...]
  wheelchair:
    description: Filter example.
    type: array
    example: ["yes", "no", "limited", "designated"]
  smoking:
    description: Filter example.
    type: array
    example: ["dedicated","yes","no","separated","isolated","outside"]
  fee:
    description: Filter example.
    type: array
    example: ["yes", "no"]

  # List response object
  LocationsListResponse:
    description: "The POI categories list JSON response"
    type: object
    title: "Openpoiservice category list response"

  # Poi response object
  LocationsPoiResponse:
    description: "The POI response GeoJSON FeatureCollection"
    type: "object"
    properties:
      type:
        type: "string"
        default: "FeatureCollection"
      features:
        type: "array"
        items:
          $ref: "#/definitions/location_features"
    title: "Openpoiservice poi response"

  # Stats response object
  LocationsStatsResponse:
    description: "The POI stats JSON response"
    type: "object"
    properties:
      places:
        type: "object"
        $ref: "#/definitions/places_object"

    title: "Openpoiservice stats response"

  places_object:
    type: object
    properties:
      category_group_id:
        type: object
        $ref: "#/definitions/stats_object"
      total_count:
        type: integer
    additionalProperties:
      type: object
      $ref: "#/definitions/stats_object"
    title: "Places object"

  stats_object:
    type: object
    properties:
      categories:
        type: object
        $ref: "#/definitions/category_object"
      name:
        type: string
        description: name of group
      total_count:
        type: integer
    title: "Stats object"

  category_object:
    type: object
    properties:
      category_id:
        type: integer
    additionalProperties:
      type: object

  location_features:
    type: "object"
    properties:
      type:
        type: "string"
        default: "Feature"
      geometry:
        type: "object"
        $ref: "#/definitions/location_features_geometry"
      feature_properties:
        type: "object"
        $ref: "#/definitions/location_features_properties"
    title: "GeoJSON features object"

  location_features_geometry:
    properties:
      type:
        type: "string"
        default: "Point"
      coordinates:
        type: "array"
        items:
          type: "number"
          format: "double"
        maxItems: 2
        minItems: 2
    title: "GeoJSON geometry object"

  location_features_properties:
    title: "GeoJSON properties object"
    properties:
      osm_id:
        type: "number"
      osm_type:
        type: "number"
      distance:
        type: "number"
      category_ids:
        type: "object"
        $ref: "#/definitions/location_features_properties_category_ids"
      osm_tags:
        type: "object"
        $ref: "#/definitions/location_features_properties_osm_tags"

  location_features_properties_category_ids:
    properties:
      category_id:
        type: "object"
        properties:
          category_name:
            type: "string"
          category_group:
            type: "number"

  location_features_properties_osm_tags:
    type: "object"
    properties:
      name:
        type: "string"
      address:
        type: "string"
      website:
        type: "string"
      opening_hours:
        type: "string"
      wheelchair:
        type: "string"
      distance:
        type: "string"
      fee:
        type: "string"