openapi: 3.2.0
info:
  title: Entur Place API
  version: 2026.09.1
  contact:
    name: Team Ruter og reiseplanlegging
    url: https://developer.entur.org
  license:
    name: EUPL-1.2
    url: https://opensource.org/licenses/EUPL-1.2
  description: 'Operations tagged Place across 2 of this provider''s published API definitions: entur-geocoder-openapi.json, entur-geocoder-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.entur.io/geocoder
security:
- {}
tags:
- name: Place
paths:
  /v3/place:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Place
      summary: Place lookup
      description: Look up one or more places by ID
      operationId: place
      parameters:
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Matching places
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              examples:
                default:
                  value:
                    type: FeatureCollection
                    features:
                    - type: Feature
                      geometry:
                        type: Point
                        coordinates:
                        - 10.7522
                        - 59.911
                      properties:
                        id: NSR:StopPlace:59872
                        names:
                          default: Oslo S
                          display: Oslo S, Oslo
                        layer: stopPlace
                        source: nsr
                        stopPlaceRole: parent
                    metadata:
                      query:
                        limit: 10
                        lang: 'no'
                      resultCount: 1
                      timestamp: '2025-03-04T11:00:00Z'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    status: 400
                    title: Bad Request
                    detail: Parameter 'ids' is required
    servers:
    - url: https://api.entur.io/geocoder
components:
  schemas:
    Layer:
      type: string
      enum:
      - address
      - street
      - stopPlace
      - groupOfStopPlaces
      - poi
      - place
      examples:
      - stopPlace
    QueryInfo:
      required:
      - lang
      - limit
      type: object
      properties:
        text:
          type: string
          examples:
          - Oslo S
        lat:
          type: number
          format: double
          examples:
          - 59.911
        lon:
          type: number
          format: double
          examples:
          - 10.7522
        limit:
          type: integer
          examples:
          - 10
        lang:
          type: string
          examples:
          - 'no'
        filters:
          $ref: '#/components/schemas/Filters'
    Feature:
      required:
      - geometry
      - properties
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - Feature
        geometry:
          $ref: '#/components/schemas/Geometry'
        properties:
          $ref: '#/components/schemas/Place'
        bbox:
          maxItems: 4
          minItems: 4
          type: array
          description: GeoJSON bounding box `[minLon, minLat, maxLon, maxLat]`. Present for features with a real extent (streets, groups of stop places); omitted for point features.
          items:
            type: number
          examples:
          - - 10.73
            - 59.91
            - 10.76
            - 59.92
    Names:
      required:
      - default
      - display
      type: object
      properties:
        default:
          type: string
          description: Official name
          examples:
          - Oslo S
        label:
          type: string
          description: Common or colloquial name
          examples:
          - Oslo Sentralstasjon
        display:
          type: string
          description: Formatted name with locality context, suitable for display
          examples:
          - Oslo S, Oslo
    Error:
      required:
      - status
      - title
      type: object
      properties:
        status:
          type: integer
          examples:
          - 400
        title:
          type: string
          examples:
          - Bad Request
        detail:
          type: string
          examples:
          - Parameter 'lat' is required
    Metadata:
      required:
      - query
      - resultCount
      - timestamp
      type: object
      properties:
        query:
          $ref: '#/components/schemas/QueryInfo'
        resultCount:
          type: integer
          examples:
          - 5
        timestamp:
          type: string
          description: Response generation time as an ISO 8601 instant (UTC).
          format: date-time
          examples:
          - '2025-03-04T11:00:00Z'
    Place:
      required:
      - id
      - layer
      - names
      - source
      type: object
      properties:
        id:
          type: string
          examples:
          - NSR:StopPlace:59872
        names:
          $ref: '#/components/schemas/Names'
        layer:
          $ref: '#/components/schemas/Layer'
        address:
          $ref: '#/components/schemas/Address'
        categories:
          type: array
          items:
            type: string
          examples:
          - - restaurant
        fareZones:
          type: array
          description: Zones the place is in; they overlap, so a stop can be in several. A multimodal parent lists its own plus its children's, so use `multimodal=child` for per-departure zones.
          items:
            type: string
          examples:
          - - RUT:FareZone:4
        transportModes:
          type: array
          items:
            $ref: '#/components/schemas/TransportMode'
        stopPlaceTypes:
          type: array
          description: NeTEx StopPlaceType values (same value set as the `stopPlaceTypes` filter parameter)
          items:
            type: string
          examples:
          - - onstreetBus
        stopPlaceRole:
          type: string
          description: 'A stop place''s role in the parent-child hierarchy: `parent` (aggregates child stops), `child`, or `standalone`. Present on `stopPlace` features; absent on other layers and on stop places not yet reindexed. Treat an absent or unrecognised value as unknown, not `standalone`. (`parent`/`child` both mean multimodal.)'
          enum:
          - parent
          - child
          - standalone
          examples:
          - parent
        source:
          type: string
          description: Data source identifier (same values as the sources filter)
          enum:
          - openstreetmap
          - kartverket-matrikkelenadresse
          - kartverket-stedsnavn
          - nsr
          - custom-poi
          examples:
          - nsr
        distance:
          type: number
          description: Distance from the reverse query point in kilometres (3-decimal precision). Present on `/v3/reverse` responses only; the field is omitted (not `null`) on autocomplete and place lookup.
          format: double
          examples:
          - 0.142
        description:
          type: object
          additionalProperties:
            type: string
          description: Per-language description. Keys are ISO 639-2 alpha-3 language codes (`nor`, `eng`, etc.). The field is omitted (not `null`) when the underlying record has no description.
          examples:
          - nor: Norges nasjonalteater
            eng: Norway's national theatre
    Result:
      required:
      - features
      - metadata
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
        metadata:
          $ref: '#/components/schemas/Metadata'
        bbox:
          maxItems: 4
          minItems: 4
          type: array
          description: '[minLon, minLat, maxLon, maxLat]'
          items:
            type: number
          examples:
          - - 10.7335
            - 59.911
            - 10.7522
            - 59.9144
    TransportMode:
      required:
      - mode
      type: object
      properties:
        mode:
          type: string
          examples:
          - bus
        subMode:
          type: string
          examples:
          - localBus
    Filters:
      type: object
      properties:
        layers:
          type: array
          items:
            $ref: '#/components/schemas/Layer'
        sources:
          type: array
          items:
            type: string
        countries:
          type: array
          items:
            type: string
        counties:
          type: array
          items:
            type: string
        localities:
          type: array
          items:
            type: string
        fareZones:
          type: array
          items:
            type: string
        fareZoneAuthorities:
          type: array
          items:
            type: string
        stopPlaceTypes:
          type: array
          items:
            type: string
        multimodal:
          type: string
          enum:
          - parent
          - child
          - all
      description: Echoes the request filters as sent, not the effective filter set.
    Address:
      type: object
      properties:
        streetName:
          type: string
          examples:
          - Jernbanetorget
        houseNumber:
          type: string
          examples:
          - '1'
        postalCode:
          type: string
          examples:
          - '0154'
        locality:
          type: string
          examples:
          - Oslo
        localityId:
          type: string
          examples:
          - KVE:TopographicPlace:0301
        borough:
          type: string
          examples:
          - Sentrum
        boroughId:
          type: string
          examples:
          - KVE:Borough:34200502
        county:
          type: string
          examples:
          - Oslo
        countyId:
          type: string
          examples:
          - KVE:TopographicPlace:03
        countryCode:
          type: string
          examples:
          - 'no'
    Geometry:
      required:
      - coordinates
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - Point
        coordinates:
          maxItems: 2
          minItems: 2
          type: array
          description: '[longitude, latitude]'
          items:
            type: number
          examples:
          - - 10.7522
            - 59.911
  parameters:
    Ids:
      name: ids
      in: query
      description: Place IDs to look up (at most 100)
      required: true
      style: form
      explode: false
      schema:
        maxItems: 100
        type: array
        items:
          type: string
      examples:
        default:
          value:
          - NSR:StopPlace:337
          - NSR:StopPlace:59872
    X-Correlation-Id:
      name: X-Correlation-Id
      in: header
      description: Correlation id
      required: false
      style: simple
      explode: false
      schema:
        type: string
    Language:
      name: lang
      in: query
      description: Language code for result names
      required: false
      style: form
      explode: true
      schema:
        type: string
        default: 'no'
      examples:
        default:
          value: 'no'
    ET-Client-Name:
      name: ET-Client-Name
      in: header
      description: 'Entur Client Header.

        It is required that all consumers identify themselves by using this header.

        Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers.

        The structure of ET-Client-Name should be: `<company>-<application>`.'
      required: false
      style: simple
      explode: false
      schema:
        type: string
externalDocs:
  description: Geocoder documentation and v3 migration guide
  url: https://developer.entur.no/docs/open-services/geocoder
x-refined-from:
- entur-geocoder-openapi.json
- entur-geocoder-openapi.yml