openapi: 3.0.1
info:
  title: Codelist API
  description: Codelist API for codelists used by other web feature and geocoding
    services provided by the National Land Survey of Finland.
  contact:
    name: Technical support for APIs
    url: https://www.maanmittauslaitos.fi/tietoa-maanmittauslaitoksesta/yhteystiedot/verkkopalveluiden-tuki
    email: sovellustuki@maanmittauslaitos.fi
  license:
    name: Data accessed from the API is licensed by the National Land Survey open
      data CC 4.0 licence.
    url: https://www.maanmittauslaitos.fi/en/opendata-licence-cc40
  version: "1.0"
servers:
- url: "https://{environment}.maanmittauslaitos.fi"
  variables:
    environment:
      default: beta-paikkatieto
      enum:
      - beta-paikkatieto
      - beta-karttakuva
paths:
  /catalogue/v1/codelistgroups/all:
    get:
      summary: return list of codelistgroups
      operationId: getAllCodelistGroups
      parameters:
      - name: lang
        in: query
        schema:
          type: string
          default: fin
      responses:
        default:
          description: codelistgroups
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/CodeListCollection"
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/id:
    get:
      summary: return codelist keys matching search term within codelistgroup
      operationId: getAnyCodelistByQuery
      parameters:
      - name: id
        in: query
        description: codelist id
        required: true
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      - name: codelist
        in: query
        description: codelist names (use comma as separator)
        schema:
          type: array
          items:
            type: string
      responses:
        default:
          description: codelists in codelistgroup matching search term
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/CodeListAnyResponse"
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/any:
    get:
      summary: return codelist values matching search term within codelistgroup
      operationId: getAnyCodelistValue
      parameters:
      - name: q
        in: query
        description: codelist value key
        required: true
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      - name: codelist
        in: query
        description: codelist names (use comma as separator)
        schema:
          type: array
          items:
            type: string
      responses:
        default:
          description: codelists in codelistgroup matching search term
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/CodeListAnyResponse"
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/{codelist}/any:
    get:
      summary: return codelist values matching search term within given codelistgroup
        and codelist
      operationId: getCodelistAnyCodelistValue
      parameters:
      - name: q
        in: query
        description: codelist group name
        required: true
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      - name: codelist
        in: path
        description: codelist name (use dash (-) as wildcard)
        required: true
        schema:
          type: string
      responses:
        default:
          description: 'matching codelists in codelistgroup '
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/CodeListAnyResponse"
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/{codelist}/items/{key}:
    get:
      summary: return information on specific codelist value
      operationId: getCodelistValue
      parameters:
      - name: semver
        in: query
        description: codelist version (semantic versioning)
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: codelist
        in: path
        description: codelist name (use dash (-) as wildcard)
        required: true
        schema:
          type: string
      - name: key
        in: path
        description: codelist value key
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      responses:
        default:
          description: codelists of a codelistgroup
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/CodeListValueResponse"
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/{codelist}/items:
    get:
      summary: return all values within codelistgroup and codelist
      operationId: getCodelistValues
      parameters:
      - name: semver
        in: query
        description: codelist version (semantic versioning)
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: codelist
        in: path
        description: codelist name (use dash (-) as wildcard)
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      responses:
        default:
          description: codelists of a codelistgroup (or all with dash)
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/CodeListDictionaryResponse"
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/{codelist}/codelist.html:
    get:
      operationId: getCodelistValuesAsHTML
      parameters:
      - name: semver
        in: query
        description: codelist version (semantic versioning)
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: codelist
        in: path
        description: codelist name (use dash (-) as wildcard)
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      responses:
        default:
          description: default response
          content:
            text/html: {}
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/{codelist}/inspire.json:
    get:
      operationId: getCodelistValuesAsInspireJSON
      parameters:
      - name: semver
        in: query
        description: codelist version (semantic versioning)
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: codelist
        in: path
        description: codelist name (use dash (-) as wildcard)
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      responses:
        default:
          description: default response
          content:
            application/json: {}
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/{codelist}/items/i18n.json:
    get:
      summary: return all codelist values modeled as locale JSON output
      operationId: getCodelistValuesAsLocaleJson
      parameters:
      - name: semver
        in: query
        description: codelist version (semantic versioning)
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: codelist
        in: path
        description: codelist name (use dash (-) as wildcard)
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      responses:
        default:
          description: codelist valuess as locale JSON
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/CodeListValueLabelMap"
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/{codelist}/items.xlsx:
    get:
      operationId: getCodelistValuesAsXSLX
      parameters:
      - name: semver
        in: query
        description: codelist version (semantic versioning)
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: codelist
        in: path
        description: codelist name (use dash (-) as wildcard)
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      responses:
        default:
          description: default response
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: {}
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists/{codelist}/schema.xsd:
    get:
      summary: 'return all codelist values modeled as XSD enum '
      operationId: getCodelistValuesAsXsd
      parameters:
      - name: semver
        in: query
        description: codelist version (semantic versioning)
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: codelist
        in: path
        description: codelist name (use dash (-) as wildcard)
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: _any_
      responses:
        default:
          description: codelist values as schema
          content:
            text/xml;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/CodeListValueLabelMap"
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists:
    get:
      summary: return list of codelists in group
      operationId: getCodelists
      parameters:
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      responses:
        default:
          description: codelists of a codelistgroup (or all with dash)
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/CodeListCollection"
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists.tar:
    get:
      summary: return all codelists as TAR package
      operationId: getCodelistsAsTar
      parameters:
      - name: semver
        in: query
        description: codelist version (semantic versioning)
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      responses:
        default:
          description: codelists grouped by locale and codelistgroup
          content:
            application/x-tar: {}
  /catalogue/v1/codelistgroups/{codelistgroup}/codelists.zip:
    get:
      summary: return all codelists as ZIP package
      operationId: getCodelistsAsZip
      parameters:
      - name: semver
        in: query
        description: codelist version (semantic versioning)
        schema:
          type: string
      - name: codelistgroup
        in: path
        description: codelist group name
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: output locale for localized values in response
        schema:
          type: string
          default: fin
      responses:
        default:
          description: codelists grouped by locale and codelistgroup
          content:
            application/zip: {}
components:
  schemas:
    CodeListStatus:
      type: string
      enum:
      - valid
      - superseded
      - retired
      - submitted
      - invalid
    CodeListLang:
      type: string
      enum:
      - fin
      - swe
      - sma
      - sme
      - smi
      - smj
    CodeListCollection:
      type: object
      properties:
        codelists:
          type: array
          items:
            $ref: "#/components/schemas/CodeListLink"
    CodeListAnyResponse:
      type: object
      properties:
        rawTerm:
          type: string
        searchTerm:
          type: string
        searchTermParts:
          type: array
          items:
            type: string
        searchTermPartCount:
          type: integer
        matchedParts:
          type: array
          items:
            type: string
        matchingCodeLists:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/CodeListDictionary"
        similarTerms:
          type: array
          items:
            $ref: "#/components/schemas/CodeListTerm"
    CodeListValueLabelMap:
      type: object
      additionalProperties:
        type: string
    CodeListValue:
      type: object
      properties:
        value:
          type: string
        label:
          type: string
        description:
          type: string
          nullable: true
        status:
          $ref: "#/components/schemas/CodeListStatus"
        lang:
          $ref: "#/components/schemas/CodeListLang"
        links:
          $ref: "#/components/schemas/CodeListLinkDictionary"
    CodeListLink:
      type: object
      properties:
        name:
          type: string
        title:
          type: string
        description:
          type: string
          nullable: true
        lang:
          $ref: "#/components/schemas/CodeListLang"
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
    CodeListLinkDictionary:
      type: array
      nullable: true
      items:
        $ref: "#/components/schemas/link"
    CodeListDictionaryResponse:
      type: object
      properties:
        name:
          type: string
        values:
          $ref: "#/components/schemas/CodeListDictionary"
    CodeListDictionary:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/CodeListValue"
    CodeListValueResponse:
      allOf:
      - $ref: "#/components/schemas/CodeListValue"
      - required:
        - type
        type: object
        properties:
          startdate:
            type: string
            format: date
            nullable: true
          enddate:
            type: string
            format: date
            nullable: true
          type:
            type: string
            default: CodeListValue
            enum:
            - CodeListValue
    CodeListTerm:
      type: object
      properties:
        text:
          type: string
        similarity:
          type: number
        word_similarity:
          type: number
        count:
          type: integer
    exception:
      required:
      - code
      type: object
      properties:
        code:
          type: string
        description:
          type: string
    link:
      required:
      - href
      type: object
      properties:
        href:
          type: string
        rel:
          type: string
          example: prev
        type:
          type: string
          example: application/geo+json
        title:
          type: string
        hreflang:
          type: string
          example: en
    codelistInfo:
      required:
      - links
      - name
      type: object
      properties:
        name:
          type: string
          description: "identifier of the collection used, for example, in URIs"
        title:
          type: string
          description: a description of the features in the collection
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
    extent:
      type: object
      properties:
        crs:
          type: string
          default: http://www.opengis.net/def/crs/OGC/1.3/CRS84
          enum:
          - http://www.opengis.net/def/crs/OGC/1.3/CRS84
        spatial:
          maxItems: 6
          minItems: 4
          type: array
          items:
            maximum: 180
            minimum: -180
            type: number
        trs:
          type: string
          default: http://www.opengis.net/def/uom/ISO-8601/0/Gregorian
          enum:
          - http://www.opengis.net/def/uom/ISO-8601/0/Gregorian
        temporal:
          maxItems: 2
          minItems: 2
          type: array
          items:
            type: string
            format: date-time
    pointGeoJSON:
      required:
      - coordinates
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - Point
        coordinates:
          minItems: 2
          type: array
          items:
            type: number
    peliasResponseFeatureCollectionGeoJSON:
      required:
      - features
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - FeatureCollection
        features:
          type: array
          items:
            $ref: "#/components/schemas/featureGeoJSON"
        geocoding:
          type: object
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
        timeStamp:
          type: string
          format: date-time
        numberMatched:
          minimum: 0
          type: integer
          format: int32
        numberReturned:
          minimum: 0
          type: integer
          format: int32
    featureCollectionGeoJSON:
      required:
      - features
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - FeatureCollection
        features:
          type: array
          items:
            $ref: "#/components/schemas/featureGeoJSON"
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
        timeStamp:
          type: string
          format: date-time
        numberMatched:
          minimum: 0
          type: integer
          format: int32
        numberReturned:
          minimum: 0
          type: integer
          format: int32
    multilinestringGeoJSON:
      required:
      - coordinates
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - MultiLineString
        coordinates:
          type: array
          items:
            minItems: 2
            type: array
            items:
              minItems: 2
              type: array
              items:
                type: number
    geometryGeoJSON:
      oneOf:
      - $ref: "#/components/schemas/pointGeoJSON"
      - $ref: "#/components/schemas/linestringGeoJSON"
      - $ref: "#/components/schemas/polygonGeoJSON"
      - $ref: "#/components/schemas/multipointGeoJSON"
      - $ref: "#/components/schemas/multilinestringGeoJSON"
      - $ref: "#/components/schemas/multipolygonGeoJSON"
      - $ref: "#/components/schemas/geometrycollectionGeoJSON"
    polygonGeoJSON:
      required:
      - coordinates
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - Polygon
        coordinates:
          type: array
          items:
            minItems: 4
            type: array
            items:
              minItems: 2
              type: array
              items:
                type: number
    multipointGeoJSON:
      required:
      - coordinates
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - MultiPoint
        coordinates:
          type: array
          items:
            minItems: 2
            type: array
            items:
              type: number
    featureGeoJSON:
      required:
      - geometry
      - properties
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - Feature
        geometry:
          $ref: "#/components/schemas/geometryGeoJSON"
        properties:
          type: object
          nullable: true
        id:
          oneOf:
          - type: string
          - type: integer
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
    linestringGeoJSON:
      required:
      - coordinates
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - LineString
        coordinates:
          minItems: 2
          type: array
          items:
            minItems: 2
            type: array
            items:
              type: number
    multipolygonGeoJSON:
      required:
      - coordinates
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - MultiPolygon
        coordinates:
          type: array
          items:
            type: array
            items:
              minItems: 4
              type: array
              items:
                minItems: 2
                type: array
                items:
                  type: number
    geometrycollectionGeoJSON:
      required:
      - geometries
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - GeometryCollection
        geometries:
          type: array
          items:
            $ref: "#/components/schemas/geometryGeoJSON"
