swagger: '2.0'

info:
  title: Geosearch API
  description: Api for looking up various things based on a point and radius.
  contact:
    name: Datapunt Amsterdam
    url: https://api.data.amsterdam.nl
    email: datalab@amsterdam.nl
  license:
    name: CC0 1.0 Universal, Public Domain Dedication
    url: https://creativecommons.org/publicdomain/zero/1.0/
  version: 1.0.0
host: api.data.amsterdam.nl
basePath: /geosearch
schemes:
  - https
produces:
  - application/json
parameters:
  xParam:
    name: x
    in: query
    description:  X (rd) coordinate to search for. Requires a complementing Y parameter. example (121848)
    required: false
    type: number
    format: double
  yParam:
    name: y
    in: query
    description: Y (rd) coordinate to search for. Requires a complementing X parameter. example (487307)
    required: false
    type: number
    format: double
  latParam:
    name: lat
    in: query
    description: latitude of coordinate to search for. Example value 52.372239620672204 Requires a complementing lon parameter.
    required: false
    type: number
    format: double
  lonParam:
    name: lon
    in: query
    description: longitude of coordinate to search for. Example value 4.900848228657843 Requires a complementing lat parameter.
    required: false
    type: number
    format: double
  radiusParam:
    name: radius
    in: query
    description: The radius the search in approximate meters. The search is actually performed in fractions of degrees and does not take curvature and terrain into account.
    required: false
    type: number
    format: double
  limitParam:
    name: limit
    in: query
    description: The amount of results. This will only work on specific itemized resultsets (/nap, /bominslagen, /monumenten)
    required: false
    type: integer
    format: int32
paths:
  /:
    get:
      summary: Generic Geo Search in all datasets combined.
      description: >
        Search in all datasets combined.
        Required arguments:
          - x/y or lat/lon for position
          - radius for searching within radius
          - datasets - subset of datasets to search in. The /catalogus/ endpoint gives a listing of the possible values.
      parameters:
        - name: datasets
          in: query
          required: false
          type: array
          items: 
            type: string
          description: >
            Dataset and/or subset name(s) to search in presented as comma separated list.
            The /catalogus/ endpoint gives a listing of the possible values.
            
        - $ref: "#/parameters/xParam"
        - $ref: "#/parameters/yParam"
        - $ref: "#/parameters/latParam"
        - $ref: "#/parameters/lonParam"
        - $ref: "#/parameters/radiusParam"
        - $ref: "#/parameters/limitParam"

      tags:
        - Geosearch
      responses:
        200:
          description: An array of items that are located within the given radius of the given location that match the requested type(s)
  /catalogus/:
    get:
      summary: List Datasets available for searching for current user.
      description: >
        List all Dataset names available to be used as `Dataset` parameter in Generic Search endpoint (url: `/?datasets=`).

        Based on authorisation scopes, users may see different list of datasets.
      tags:
        - Geosearch
      responses:
        200:
          description: An array of items that are located within the given radius of the given location that match the requested type(s)
  /search/:
    get:
      summary: Generic Geo Search per Dataset
      description: >
        General geosearch endpoint. Required arguments are radius, item and
        (x and y) or (lat and lon) for position. When both x/y and lat/lon are passed the behavior is not specied and could vary. Note they are all marked optional due to schema limitations
      parameters:
        - name: item
          in: query
          required: true
          type: string
          enum:
            - peilmerk
            - meetbout
            - bominslag
            - gevrijwaardgebied
            - uitgevoerdonderzoek
            - verdachtgebied
            - bouwblok
            - buurt
            - buurtcombinatie
            - gebiedsgerichtwerken
            - grootstedelijkgebied
            - ligplaats
            - openbareruimte
            - pand
            - stadsdeel
            - standplaats
            - unesco
            - verblijfsobject
            - beperking
            - kadastraal_object
            - biz
          description: >
            Type of item(s) to look for.
        - $ref: "#/parameters/xParam"
        - $ref: "#/parameters/yParam"
        - $ref: "#/parameters/latParam"
        - $ref: "#/parameters/lonParam"
        - $ref: "#/parameters/radiusParam"
        - $ref: "#/parameters/limitParam"

      tags:
        - Geosearch
      responses:
        200:
          description: An array of items that are located within the given radius of the given location that match the requested type(s)
  /nap/:
    get:
      summary: Search all of the NAP dataset
      description: >
        The NAP dataset contains Meetbouten en Peilmerken. The search works similar to the /search endpoint in that you need to supply either x/y or lat/lon. Providing both sets has no guaranteed order
      parameters:
        - $ref: "#/parameters/xParam"
        - $ref: "#/parameters/yParam"
        - $ref: "#/parameters/latParam"
        - $ref: "#/parameters/lonParam"
        - $ref: "#/parameters/radiusParam"
        - $ref: "#/parameters/limitParam"
      tags:
        - Geosearch
      responses:
        200:
          description: An array of items that are located within the given radius of the given location that match the requested type(s)
  /munitie/:
    get:
      summary: Search for gevrijwaardgebied, uitgevoerdonderzoek and verdachtgebied areas in Munitie dataset
      description: >
        The Munitie dataset contains information about explosives from the second world war. It includes locations of impact, areas that are suspected of having unexploded ammunition and areas that have been searched for explosives.
        You need to supply either x/y or lat/lon. Providing both sets has no guaranteed order!
      parameters:
        - $ref: "#/parameters/xParam"
        - $ref: "#/parameters/yParam"
        - $ref: "#/parameters/latParam"
        - $ref: "#/parameters/lonParam"
      tags:
        - Geosearch
      responses:
        200:
          description: A list of areas, mathing the requested type, that the given location falls within.
  /bominslag/:
    get:
      summary: Search for bominslag in Munitie dataset
      description: >
        The Munitie dataset contains information about explosives from the second world war. It includes locations of impact, areas that are suspected of having unexploded ammunition and areas that have been searched for explosives.
        You need to supply either x/y or lat/lon. Providing both sets has no guaranteed order!
      parameters:
        - $ref: "#/parameters/xParam"
        - $ref: "#/parameters/yParam"
        - $ref: "#/parameters/latParam"
        - $ref: "#/parameters/lonParam"
        - $ref: "#/parameters/radiusParam"
        - $ref: "#/parameters/limitParam"
      tags:
        - Geosearch
      responses:
        200:
          description: An array of items that are located within the given radius of the given location that match the requested type(s)

  /monumenten/:
    get:
      summary: Search for monumenten in Monumenten dataset
      description: >
        The Monumenten dataset contains information about monuments including name, status, the grouping of monuments into complexes and the adjacent adresses of monuments.
        You need to supply either x/y or lat/lon. Providing both sets has no guaranteed order!
      parameters:
        - $ref: "#/parameters/xParam"
        - $ref: "#/parameters/yParam"
        - $ref: "#/parameters/latParam"
        - $ref: "#/parameters/lonParam"
        - $ref: "#/parameters/radiusParam"
        - $ref: "#/parameters/limitParam"
      tags:
        - Geosearch
      responses:
        200:
          description: An array of items that are located within the given radius of the given location that match the requested type(s)

  /atlas/:
    get:
      summary: Search all of the BAG dataset (OLD) please use /bag endpoint.
      description: >
        This includes mainly BAG (Basisregistratie Adressen en gebouwen) information. (DEPRICATED) use BAG
        Like all other geo searches either an x/y or a lat/lon tuple needs to be supplied along with a radius. When both x/y and lat/long are provided no guarantees about the coordinates used is given.
      parameters:
        - $ref: "#/parameters/xParam"
        - $ref: "#/parameters/yParam"
        - $ref: "#/parameters/latParam"
        - $ref: "#/parameters/lonParam"
        - $ref: "#/parameters/radiusParam"
      tags:
        - Geosearch
      responses:
        200:
          description: A list of areas, mathing the requested type, that the given location falls within.

  /bag/:
    get:
      summary: Search all of the Bag dataset
      description: >
        This includes mainly BAG (Basisregistratie Adressen en gebouwen) information.
        Like all other geo searches either an x/y or a lat/lon tuple needs to be supplied along with a radius. When both x/y and lat/long are provided no guarantees about the coordinates used is given.
      parameters:
        - $ref: "#/parameters/xParam"
        - $ref: "#/parameters/yParam"
        - $ref: "#/parameters/latParam"
        - $ref: "#/parameters/lonParam"
        - $ref: "#/parameters/radiusParam"
      tags:
        - Geosearch
      responses:
        200:
          description: A list of areas, mathing the requested type, that the given location falls within.

  /biz/:
    get:
      summary: Search for BIZ (BedrijfsInvesteringsZones)
      description: >
        This returns the BedrijfsInvesteringsZones (Winkeliersverenigingen) in which the given point is located.
        Like all other geo searches either an x/y or a lat/lon tuple needs to be supplied. When both x/y and lat/long are provided no guarantees about the coordinates used is given.
      parameters:
        - $ref: "#/parameters/xParam"
        - $ref: "#/parameters/yParam"
        - $ref: "#/parameters/latParam"
        - $ref: "#/parameters/lonParam"
      tags:
        - Geosearch
      responses:
        200:
          description: A list of areas, matching the requested type, that the given location falls within.
