geo-v1.yaml

openapi: 3.0.2
info:
  title: Geo Information API
  description: |-
    The Geo Information REST API provides information about points of interest (places), routes and dossiers from the ETHorama database as well as maps from e-rara and e-maps. Place data is available as GeoJSON.
        
    ➜ [OAS 3 Swagger Documentation](https://eth-library.github.io/apiplatform-swagger/geo/v1/)

    ➜ [ETHorama Application](https://ethorama.library.ethz.ch/)
  version: '1.0.1'
  termsOfService: https://developer.library.ethz.ch/terms
  contact:
    name: API Management ETH Library
    email: api@library.ethz.ch
    url: https://library.ethz.ch
  license:
    url: https://developer.library.ethz.ch/terms
    name: Bibliographic metadata that are not specifically marked are free for general use (Public Domain). Documents, images or other digital objects linked in metadata may be subject to other copyright restrictions. Whenever possible, the licence of the referenced digital objects is indicated in the metadata. In case of doubt, the licence can be inquired at api@library.ethz.ch.
servers:
  - url: https://api.library.ethz.ch/geo/v1/
    description: Production
paths:
  /places:
    get:
      tags:
        - Places
      description: |-
        Returns all places defined in the ETHorama database.
      responses:
        '200':
          description: Returns Places as GeoJSON
          content:
            application/json: {}
        '500':
          description: server error
  /places/geojson:
    get:
      tags:
        - Places
      description: |-
        Returns all or filtered places defined in the ETHorama database as GeoJSON.
      parameters:
        - name: nearto
          schema:
            type: string
          in: query
          required: false
          description: |-
            Places nearto a point, which is defined by the comma separated value: lat, lng, distance in meter (default: 1000). 

             Example: nearto=47.383046,8.536655,2000
      responses:
        '200':
          description: Returns a geoJSON FeatureCollection
          content:
            application/json: {}
        '500':
          description: server error
  /places/geojson/{id}:
    get:
      tags:
        - Places
      description: Returns place (by POI ID or Wikidata QID) as geoJSON
      parameters:
        - name: id
          schema:
            type: string
          in: path
          required: true
          description: ID from ETHorama (2o6hEWTkOGDL35HANR5c) or Wikidata QID (Q64093)
      responses:
        '200':
          description: Returns a place as geoJSON Feature
          content:
            application/json: {}
        '404':
          description: there is no place available with this id
  /geo-data:
    get:
      tags:
        - Geodata
      description: |-
        Returns geodata: pois (from ETHorama), e-rara maps, e-maps, places (Marc 651 from e-rara and e-maps) and publication places.
      parameters:
        - name: lat
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns the pois or places (subject added entry-geographic names from marc 651) that are near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).And returns the maps from e-rara and e-maps on which the defined point is located.

            Example: lat=47.349952
        - name: lon
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns the pois or places (subject added entry-geographic names from marc 651) that are near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).And returns the maps from e-rara and e-maps on which the defined point is located.

            Example: lon=8.490838
        - name: dist
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns the pois or places (subject added entry-geographic names from marc 651) that are near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).And returns the maps from e-rara and e-maps on which the defined point is located.

            Example: dist=1000
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns the data for the search term (q).The parameter "q" is alternative to "lat"/"lon".

            Example: q=kyburg
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should edges/relations also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns geodata as GeoJSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /maps:
    get:
      tags:
        - Maps
      description: |-
        Returns maps from e-rara and e-maps.
      parameters:
        - name: lat
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns maps from e-rara and e-maps on which the defined point is located.

            Example: lat=47.349952
        - name: lon
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns maps from e-rara and e-maps on which the defined point is located.

            Example: lon=8.490838
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns the data for the search term (q).The parameter "q" is alternative to "lat"/"lon".

            Example: q=kyburg
      responses:
        '200':
          description: Returns maps as GeoJSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /locations:
    get:
      tags:
        - Locations
      description: |-
        Returns locations: pois (from ETHorama), places (Marc 651 from e-rara and e-maps) and publication places.
      parameters:
        - name: lat
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns the pois or places (subject added entry-geographic names from marc 651) that are near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

            Example: lat=47.349952
        - name: lon
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns the pois or places (subject added entry-geographic names from marc 651) that are near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

            Example: lon=8.490838
        - name: dist
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns the pois or places (subject added entry-geographic names from marc 651) that are near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

            Example: dist=1000
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns the data for the search term (q).The parameter "q" is alternative to "lat"/"lon".

            Example: q=kyburg
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to e-rara, e-maps etc. also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns locations as GeoJSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error
  /pub-places:
    get:
      tags:
        - Publication places
      description: |-
        Returns publication places
      parameters:
        - name: lat
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns the publication places (marc 751 or marc 264) that are near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

            Example: lat=47.349952
        - name: lon
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns the publication places (marc 751 or marc 264) that are near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

            Example: lon=8.490838
        - name: dist
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns the publication places (marc 751 or marc 264) that are near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

            Example: dist=1000
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns publication places (marc 751 or marc 264) for the search term (q).The parameter "q" is alternative to "lat"/"lon".

            Example: q=kyburg
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to e-rara, e-maps also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns publication places as GeoJSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /pois:
      get:
        tags:
          - Pois
        description: |-
          Returns pois and related resources from e-rara defined in the ETHorama database. References of POIs to e-pics and other data are not yet available here.
        parameters:
          - name: lat
            schema:
              type: number
            in: query
            required: false
            description: |-
              Returns the pois near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

              Example: lat=47.349952
          - name: lon
            schema:
              type: number
            in: query
            required: false
            description: |-
              Returns the pois near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

              Example: lon=8.490838
          - name: dist
            schema:
              type: number
            in: query
            required: false
            description: |-
              Returns the pois near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

              Example: dist=1000

          - name: q
            schema:
              type: string
            in: query
            required: false
            description: |-
              Returns the data for the search term (q).The parameter "q" is alternative to "lat"/"lon".

              Example: q=kyburg
          - name: edges
            schema:
              type: boolean
            in: query
            required: false
            description: |-
              Should the edges/relations to content items, dossiers and routes also be returned (default: true)?

              Example: edges=false
        responses:
          '200':
            description: Returns geodata as GeoJSON
            content:
              application/json: {}
          '400':
            description: bad request
          '500':
            description: server error

  /pois/{id}:
    get:
      tags:
        - Pois
      description: Returns a poi and related resources defined in the ETHorama database. References of POIs to e-pics and other data are not yet available here.
      parameters:
        - name: id
          schema:
            type: string
          in: path
          required: true
          description: poi ID 
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to content items, dossiers and routes also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns geodata as GeoJSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /poi-items:
      get:
        tags:
          - Poi items
        description: |-
          Returns content items (e-rara, emaps, e-pics, e-periodica etc) of pois defined in the ETHorama database. The content items are resources of the eth library that are associated with the POI and describe it.
        parameters:
          - name: q
            schema:
              type: string
            in: query
            required: true
            description: |-
              Returns the content items for the search term (q).

              Example: q=Gotthardtunnel
          - name: edges
            schema:
              type: boolean
            in: query
            required: false
            description: |-
              Should the edges/relations to dossiers, routes and pois also be returned (default: true)?

              Example: edges=false
        responses:
          '200':
            description: Returns content items
            content:
              application/json: {}
          '400':
            description: bad request
          '500':
            description: server error
  /poi-items/{id}:
      get:
        tags:
          - items
        description: Returns a content item (e-rara, emaps, e-pics, e-periodica etc) of a poi defined in the ETHorama database.
        parameters:
          - name: id
            schema:
              type: string
            in: path
            required: true
            description: content item ID 
          - name: edges
            schema:
              type: boolean
            in: query
            required: false
            description: |-
              Should the edges/relations to dossiers, routes and pois also be returned (default: true)?

              Example: edges=false
        responses:
          '200':
            description: Returns content item
            content:
              application/json: {}
          '400':
            description: bad request
          '500':
            description: server error
  /epics-items:
      get:
        tags:
          - e-pics items
        description: |-
          Returns images from e-pics.
        parameters:
          - name: q
            schema:
              type: string
            in: query
            required: false
            description: |-
              Returns the images for the search term (q).

              Example: q=uetliberg
          - name: edges
            schema:
              type: boolean
            in: query
            required: false
            description: |-
              Should the edges/relations to contributors also be returned (default: true)?

              Example: edges=false
        responses:
          '200':
            description: Returns content items
            content:
              application/json: {}
          '400':
            description: bad request
          '500':
            description: server error

  /e-rara-maps:
    get:
      tags:
        - e-rara
      description: |-
        Returns maps from e-rara (ETH).
      parameters:
        - name: lat
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns maps in which the point defined by lat (latitude) and lon (longitude) is located.

            Example: lat=47.349952
        - name: lon
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns maps in which the point defined by lat (latitude) and lon (longitude) is located.

            Example: lon=8.490838
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns maps for the search term (q).The parameter "q" is alternative to "lat"/"lon".

            Example: q=kyburg
      responses:
        '200':
          description: Returns geodata as GeoJSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /e-rara-maps/{id}:
    get:
      tags:
        - e-rara
      description: Returns an e-rara map and related resources.
      parameters:
        - name: id
          schema:
            type: string
          in: path
          required: true
          description: MMS ID 
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to topics, poi-items, contributors etc. also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns geodata as GeoJSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /e-maps:
    get:
      tags:
        - e-maps
      description: |-
        Returns maps from e-maps.
      parameters:
        - name: lat
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns maps in which the point defined by lat (latitude) and lon (longitude) is located.

            Example: lat=47.349952
        - name: lon
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns maps in which the point defined by lat (latitude) and lon (longitude) is located.

            Example: lon=8.490838
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns maps for the search term (q).The parameter "q" is alternative to "lat"/"lon".

            Example: q=kyburg
      responses:
        '200':
          description: Returns geodata as GeoJSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /e-maps/{id}:
    get:
      tags:
        - e-maps    
      description: Returns an e-map and related resources.
      parameters:
        - name: id
          schema:
            type: string
          in: path
          required: true
          description: MMS ID 
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to topics, contributors etc. also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns geodata as GeoJSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /dossiers:
    get:
      tags:
        - Dossiers    
      description: |-
        Returns the dossiers and related resources defined in the ETHorama database.
      parameters:
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns dossiers for the search term (q).

            Example: q=bahnen
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to pois, poi-items and e-rara-items also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns dossiers as JSON
          content:
            application/json: {}
        '500':
          description: server error

  /dossiers/{id}:
    get:
      tags:
        - Dossiers    
      description: Returns a dossier and related resources defined in the ETHorama database.
      parameters:
        - name: id
          schema:
            type: string
          in: path
          required: true
          description: dossier ID 
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to pois, poi-items and e-rara-items also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns dossier as JSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /routes:
    get:
      tags:
        - Routes    
      description: |-
        Returns routes and related resources defined in the ETHorama database.
      parameters:
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns routes for the search term "q".

            Example: q=berg
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to pois, poi-items and e-rara-items also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns routes as JSON
          content:
            application/json: {}
        '500':
          description: server error

  /routes/{id}:
    get:
      tags:
        - Routes       
      description: Returns a route and related resources defined in the ETHorama database.
      parameters:
        - name: id
          schema:
            type: string
          in: path
          required: true
          description: route ID 
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to pois, poi-items and e-rara-items also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns route as JSON
          content:
            application/json: {}
        '400':
          description: bad request
        '500':
          description: server error

  /contributors:
    get:
      tags:
        - Contributors    
      description: |-
        Returns contributors (from e-rara and e-maps) and related resources.
      parameters:
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns contributors and related resources for the search term (q).

            Example: q=Heim, Albert
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to e-maps and e-rara-items also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns contributors and related resources as JSON
          content:
            application/json: {}
        '500':
          description: server error

  /topics:
    get:
      tags:
        - Topics     
      description: |-
        Returns topics (from e-rara and e-maps) and related resources.
      parameters:
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns topics and related resources for the search term (q).

            Example: q=eisenbahn
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to e-maps and e-rara-items also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns topics as JSON
          content:
            application/json: {}
        '500':
          description: server error

  /geo-topics:
    get:
      tags:
        - geo-topics       
      description: |-
        Returns places (subject added entry-geographic names from marc 651 of e-rara and e-maps) and related resources.
      parameters:
        - name: lat
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns places (subject added entry-geographic names from marc 651) and related resources near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

            Example: lat=47.378169444
        - name: lon
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns places (subject added entry-geographic names from marc 651) and related resources near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

            Example: lon=8.540177777
        - name: dist
          schema:
            type: number
          in: query
          required: false
          description: |-
            Returns places (subject added entry-geographic names from marc 651) and related resources near a point defined by lat (latitude) and lon (longitude) and optionally dist (distance) in metres (default: 1000).

            Example: dist=1000
        - name: q
          schema:
            type: string
          in: query
          required: false
          description: |-
            Returns places (subject added entry-geographic names from marc 651) and related resources for the search term (q).The parameter "q" is alternative to "lat"/"lon".

            Example: q=bern
        - name: edges
          schema:
            type: boolean
          in: query
          required: false
          description: |-
            Should the edges/relations to e-rara and e-maps also be returned (default: true)?

            Example: edges=false
      responses:
        '200':
          description: Returns places (subject added entry-geographic names from marc 651) and related resources as GeoJSON
          content:
            application/json: {}
        '500':
          description: server error

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apikey
security:
  - ApiKeyAuth: []
externalDocs:
  description: OAS 3 Swagger Documentation
  url: https://apisdocs.library.ethz.ch/geo/v1/