---
openapi: 3.0.3
info:
  title: v2 Belgian Streets and Addresses REST API
  description: "OpenAPI specification of the v2 Belgian Streets and Addresses (BeSt) REST API.\n\n\
    \ By relying on a consolidated dataset, this new version delivers greater performance and more\
    \ features.\
    \ An address is an identification of the fixed location of a property."
  contact:
    name: BOSA DG DT servicedesk
    email: servicedesk.DTO@bosa.fgov.be
  version: 1.9.8
tags:
- name: addresses
  description: Search for addresses
security:
  - OAuth2: []

paths:
  /belgianAddress/v2/addresses:
    get:
      tags:
      - addresses
      summary: Search for addresses
      description: A series of parameters can be used to search for addresses
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - name: xLong
        in: query
        description: X coordinate (in WGS84/GPS, Lambert72 or Lambert2008)
        schema:
          format: double
          type: number
        example: 4.231
      - name: yLat
        in: query
        description: Y coordinate (in WGS84/GPS or Lambert72 or Lambert2008)
        schema:
          format: double
          type: number
        example: 51.210
      - name: crs
        in: query
        description: Coordinate reference system
        schema:
          enum:
          - wgs84
          - lam72
          - lam08
          type: string
        example: wgs84
      - name: radius
        in: query
        description: Maximum distance (in meters)
        schema:
          minimum: 1
          maximum: 1000
          default: 100
          format: uint32
          type: integer
        example: 100
      - $ref: "#/components/parameters/MunicipalityId"
      - $ref: "#/components/parameters/NisCode"
      - $ref: "#/components/parameters/MunicipalityName"
      - $ref: "#/components/parameters/PostId"
      - $ref: "#/components/parameters/PostCode"
      - $ref: "#/components/parameters/StreetId"
      - $ref: "#/components/parameters/StreetName"
      - $ref: "#/components/parameters/HouseNumber"
      - $ref: "#/components/parameters/BoxNumber"
      - $ref: "#/components/parameters/PartialId"
      - $ref: "#/components/parameters/Status"
      - $ref: "#/components/parameters/AddressEmbed"
      - name: firstOfBuilding
        in: query
        description: Return only first address of a building (house or first boxnumber in apartment building)
        schema:
          default: true
          type: boolean  
      - $ref: "#/components/parameters/PageNo"
      - $ref: "#/components/parameters/Page"
      responses:
        '200':
          description: A (possibly empty) collection of addresses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressCollection'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/addresses/{id}:
    get:
      tags:
      - addresses
      summary: Get a specific address
      description: Get exactly 1 address object
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - name: id
        in: path
        description: URL-encoded ID
        schema:
          type: string
        required: true
      - $ref: "#/components/parameters/AddressEmbed"
      responses:
        '200':
          description: An address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        '404':
          $ref: "#/components/responses/404"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/municipalities:
    get:
      tags:
      - municipalities
      summary: Search for municipalities
      description: A series of parameters can be used to search for municipalities. Return all municipalities when no parameters are given.
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - $ref: "#/components/parameters/NisCode"
      - $ref: "#/components/parameters/PostId"
      - $ref: "#/components/parameters/PostCode"
      - $ref: "#/components/parameters/Name"
      - $ref: "#/components/parameters/PartialId"
      - $ref: "#/components/parameters/Status"
      - $ref: "#/components/parameters/PageNo"
      - $ref: "#/components/parameters/Page"
      responses:
        '200':
          description: A (possibly empty) collection of municipalities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MunicipalityCollection'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/municipalities/{id}:
    get:
      tags:
      - municipalities
      summary: Get a specific municipality
      description: Get exactly 1 municipality object
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - name: id
        in: path
        description: URL-encoded ID
        schema:
          type: string
        required: true
      responses:
        '200':
          description: A municipality
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Municipality'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        '404':
          $ref: "#/components/responses/404"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/postalInfos:
    get:
      tags:
      - postalInfos
      summary: Search for postal infos
      description: A series of parameters can be used to search for postal info. Return all postalinfos when no parameters are given.
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - $ref: "#/components/parameters/PostCode"
      - $ref: "#/components/parameters/Name"
      - $ref: "#/components/parameters/PartialId"
      - $ref: "#/components/parameters/Status"
      - $ref: "#/components/parameters/PageNo"
      - $ref: "#/components/parameters/Page"
      responses:
        '200':
          description: A (possibly empty) collection of postal info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostalInfoCollection'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/postalInfos/{id}:
    get:
      tags:
      - postalInfos
      summary: Get a specific postal info
      description: Get exactly 1 postal info object
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - name: id
        in: path
        description: URL-encoded ID
        schema:
          type: string
        required: true
      responses:
        '200':
          description: A postal info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostalInfo'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        '404':
          $ref: "#/components/responses/404"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/streets:
    get:
      tags:
      - streets
      summary: Search for streets
      description: A series of parameters can be used to search for streets
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - $ref: "#/components/parameters/MunicipalityId"
      - $ref: "#/components/parameters/NisCode"
      - $ref: "#/components/parameters/PostId"
      - $ref: "#/components/parameters/PostCode"
      - $ref: "#/components/parameters/Name"
      - $ref: "#/components/parameters/PartialId"
      - $ref: "#/components/parameters/Status"
      - $ref: "#/components/parameters/PageNo"
      - $ref: "#/components/parameters/Page"
      - $ref: "#/components/parameters/StreetEmbed"
      responses:
        '200':
          description: A (possibly empty) collection of streets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreetCollection'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/streets/{id}:
    get:
      tags:
      - streets
      summary: Get a specific street
      description: Get exactly 1 street object
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - name: id
        in: path
        description: URL-encoded ID
        schema:
          type: string
        required: true
      - $ref: "#/components/parameters/StreetEmbed"
      responses:
        '200':
          description: A street
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Street'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        '404':
          $ref: "#/components/responses/404"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/partOfMunicipalities:
    get:
      tags:
        - partOfMunicipalities
      summary: Search for parts of municipalities
      description: A series of parameters can be used to search for parts of municipalities. Return all parts of the municipalities when no parameters are given.
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - $ref: "#/components/parameters/Name"
      - $ref: "#/components/parameters/PartialId"
      - $ref: "#/components/parameters/Status"
      - $ref: "#/components/parameters/PageNo"
      - $ref: "#/components/parameters/Page"
      responses:
        '200':
          description: A (possibly empty) collection of parts of municipalities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartOfMunicipalityCollection'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/partOfMuncipalities:
    get:
      tags:
        - partOfMuncipalities
      deprecated: true
      summary: Search for parts of municipalities
      description: Deprecated, use partOfMunicipalities instead. A series of parameters can be used to search for parts of municipalities. Return all parts of the municipalities when no parameters are given.
      parameters:
      - $ref: "#/components/parameters/TraceId"
      - $ref: "#/components/parameters/Name"
      - $ref: "#/components/parameters/PartialId"
      - $ref: "#/components/parameters/Status"
      - $ref: "#/components/parameters/PageNo"
      - $ref: "#/components/parameters/Page"
      responses:
        '200':
          description: A (possibly empty) collection of parts of municipalities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartOfMunicipalityCollection'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/partOfMunicipalities/{id}:
    get:
      tags:
        - partOfMunicipalities
      summary: Get a specific part of municipality
      description: Get exactly 1 part of municipality object
      parameters:
        - $ref: "#/components/parameters/TraceId"
        - name: id
          in: path
          description: URL-encoded ID
          schema:
            type: string
          required: true
      responses:
        '200':
          description: A part of municipality
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartOfMunicipality'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        '404':
          $ref: "#/components/responses/404"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/partOfMuncipalities/{id}:
    get:
      tags:
        - partOfMuncipalities
      deprecated: true
      summary: Get a specific part of municipality
      description: Deprecated, use partOfMunicipalities instead. Get exactly 1 part of municipality object
      parameters:
        - $ref: "#/components/parameters/TraceId"
        - name: id
          in: path
          description: URL-encoded ID
          schema:
            type: string
          required: true
      responses:
        '200':
          description: A part of municipality
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartOfMunicipality'
        '400':
          $ref: "#/components/responses/400"
        '401':
          $ref: "#/components/responses/401"
        '404':
          $ref: "#/components/responses/404"
        default:
          $ref: "#/components/responses/Problem"
  /belgianAddress/v2/health:
    get:
      tags:
      - health
      summary: Health check
      description: Check if database is still reachable
      responses:
        '200':
          description: Service UP
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: UP
        '503':
          description: Service DOWN
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: DOWN
  /belgianAddress/v2/version:
    get:
      tags:
      - info
      summary: Version info
      description: Show application and data version info
      responses:
        '200':
          description: Application and data version info
          content:
            application/json:
              schema:
                type: object
                properties:
                  appVersion:
                    type: string
                  dataUpdates:
                    type: object
  /belgianAddress/v2/doc/issues.html:
    get:
      tags:
      - info
      summary: Known issues
      description: Show information about known issues and limitations.
      responses:
        '200':
          description: Page on known issues
          content:
            text/html:
              schema:
                type: string
  /belgianAddress/v2/doc/licenses/index.html:
    get:
      tags:
      - info
      summary: License info
      description: Show license overview of the various data sources and software components being used.
      responses:
        '200':
          description: Pages on licenses, copyright info and notes
          content:
            text/html:
              schema:
                type: string
  /belgianAddress/v2/doc/licenses/{doc}.txt:
    get:
      tags:
      - info
      summary: License info
      description: Show specific license, copyright info, notes...
      parameters:
        - name: doc
          in: path
          description: document name
          schema:
            type: string
          required: true
      responses:
        '200':
          description: License, copyright info or notes
          content:
            text/plain:
              schema:
                type: string
  /belgianAddress/v2/doc/openapi.yaml:
    get:
      tags:
      - info
      summary: This OpenAPI file
      description: YAML file containing OpenAPI service description
      responses:
        '200':
          description: OpenAPI file
          content:
            application/yaml:
              schema:
                type: string
  /belgianAddress/v2/doc/RELEASE-NOTES.txt:
    get:
      tags:
      - info
      summary: Release notes
      description: Show a short overview of changes since the first release
      responses:
        '200':
          description: Release notes
          content:
            text/plain:
              schema:
                type: string
components:
  parameters:
    TraceId:
      name: BelGov-Trace-Id
      in: header
      description: Audit/debug ID to uniquely identify requests or response messages. Can be freely chosen (using UUIDs is recommended).
      schema:
        type: string
        example: 123456-1234-1235-4567489798
      required: true
    AddressEmbed:
      name: embed
      in: query
      description: Embed referenced streets, municipalities ... Use 'true' to embed all referenced entities directly. Otherwise the entities are embedded in a separate key/value object. 
      schema:
        default: ['true']
        type: array
        items:
          type: string
          enum: 
            - 'true'
            - 'false'
            - streets
            - municipalities
            - partOfMunicipalities
            - postalInfos 
        example: ["streets", "municipalities", "postalInfos"]
      explode: true
    StreetEmbed:
      name: embed
      in: query
      description: Embed municipality. Use 'true' to embed the municipality directly. Otherwise municipality is embedded in a separate key/value object. 
      schema:
        default: 'true'
        type: string
        enum: 
          - 'true'
          - 'false'
          - municipalities
        example: municipalities
    HouseNumber:
      name: houseNumber
      in: query
      description: House number
      schema:
        type: string
      example: '71'
    BoxNumber:
      name: boxNumber
      in: query
      description: Box number
      schema:
        type: string
      example: '5'
    MunicipalityId:
      name: municipalityId
      in: query
      description: URL encoded BeST-ID of the municipality
      schema:
        type: string
    NisCode:
      name: nisCode
      in: query
      description: NIS code of the municipality
      schema:
        type: string
        pattern: '^\d{5}$'
      example: '23027'
    MunicipalityName:
      name: municipalityName
      in: query
      description: Name of the municipality (percent-encoded, any language, case-insensitive, accents are ignored). 
        Use '*' before/after the string to perform a substring match.
      schema:
        type: string
      examples:
        lowercase:
            value: liege
        encoded:
            value: Li%C3%A8ge
    PartialId:
      name: partialId
      in: query
      description: Partial BeST ID (without versionIdentifier)
      schema:
        type: string
    PostId:
      name: postalInfoId
      in: query
      description: URL encoded BeST-ID of the postalInfo
      schema:
        type: string
    PostCode:
      name: postCode
      in: query
      description: Postal code
      schema:
        type: string
        pattern: '^\d{4}$'
      example: '1000'
    StreetId:
      name: streetId
      in: query
      description: URL encoded BeST-ID of the street
      schema:
        type: string
    StreetName:
      name: streetName
      in: query
      description: Name of the street (any language, case-insensitive, accents are ignored, spaces must be encoded).
        Use '*' before/after the string to perform a substring match.
      schema:
        type: string
      examples: 
        encoded:
          value: Rue%20de%20la%20gare
        substring:
          value: Station*    
    Name:
      name: name
      in: query
      description: Name (any language, case-insensitive, accents are ignored, spaces must be encoded).
        Use '*' before/after the string to perform a substring match.
      schema:
        type: string
    Status:
      name: status
      in: query
      description: Status of the address, street ...
      schema:
        $ref: '#/components/schemas/Status'
    PageNo:
      name: pageNo
      in: query
      description: Page number (on paginated results. This parameter is deprecated use page instead)
      deprecated: true
      schema:
        default: 1
        minimum: 1
        format: uint32
        type: integer
      example: 5
    Page:
      name: page
      in: query
      description: Page number (on paginated results)
      schema:
        default: 1
        minimum: 1
        format: uint32
        type: integer
      example: 5
  responses:
    '400':
      description: Bad request, missing or invalid parameters
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BadRequestResponse'      
    '401':
      description: Missing or incorrect/expired OAuth access token
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponse'
    '404':
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundResponse'
    Problem:
      description: Server error or any other problem
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
  schemas:
    Name:
      type: object
      properties:
        nl:
          description: Name in Dutch, may be empty
          type: string
          example: Brussel
        fr:
          description: Name in French, may be empty
          type: string
          example: Bruxelles
        de:
          description: Name in German, may be empty
          type: string
          example: Brüssels
    ObjectReference:
      type: object
      description: Reference to object, used when the objects are not embedded (i.e. the embed parameter has not been set)
      properties:
        id:
          description: Identifier
          type: string
        href:
          description: Hyperlink to entity (street, municipality, ...)
          type: string
      additionalProperties: false
    Address:
      type: object
      required:
        - id
        - bestidentifier
        - hasStreetName
        - hasMunicipality
        - hasPostalInfo
        - houseNumber
        - status
      properties:
        id:
          description: Unique identifier, concatenation of bestIdentifier fields
          type: string
        bestidentifier:
          $ref: '#/components/schemas/BestIdentifier'
        hasStreetName:
          oneOf:
            - $ref: '#/components/schemas/ObjectReference'
            - $ref: '#/components/schemas/StreetEmbedded'
        hasMunicipality:
          oneOf:
            - $ref: '#/components/schemas/ObjectReference'
            - $ref: '#/components/schemas/MunicipalityEmbedded'
        hasPartOfMunicipality:
          oneOf:
            - $ref: '#/components/schemas/ObjectReference'
            - $ref: '#/components/schemas/PartOfMunicipalityEmbedded'
        hasPostalInfo:
          oneOf:
            - $ref: '#/components/schemas/ObjectReference'
            - $ref: '#/components/schemas/PostalInfoEmbedded'
        houseNumber:
          description: House number
          type: string
          example: '71'
        boxNumber:
          description: Box number
          type: string
          example: '5'
        status:
          $ref: '#/components/schemas/Status'
        validFrom:
          $ref: '#/components/schemas/ValidFrom'
        validTo:
          $ref: '#/components/schemas/ValidTo'
        beginLifeSpanVersion:
          $ref: '#/components/schemas/BeginLifespan'
        endLifeSpanVersion:
          $ref: '#/components/schemas/EndLifespan'
        addressPosition:
          $ref: '#/components/schemas/AddressPosition'
        isOfficiallyAssigned:
          description: Has the address been officially assigned or not
          type: boolean
          example: true
        embedded:
          $ref: '#/components/schemas/AddressEmbeddedMap'
        self:
          description: Hyperlink to individual address
          type: string
    AddressCollection:
      type: object
      required:
        - self
        - items
        - pageSize
        - total
        - totalPages
        - first
        - last
      properties:
        self:
          description: Link to self, basically the GET query being used to obtain this result
          type: string
        items:
          description: (Possibly empty) array of results
          type: array
          items:
            $ref: '#/components/schemas/Address'
        embedded:
            $ref: '#/components/schemas/AddressEmbeddedMap'  
        pageSize:
          $ref: '#/components/schemas/PageSize'
        total:
          $ref: '#/components/schemas/Total'
        totalPages:
          $ref: '#/components/schemas/TotalPages'
        first:
          $ref: '#/components/schemas/FirstPage'
        last:
          $ref: '#/components/schemas/LastPage'
        next:
          $ref: '#/components/schemas/NextPage'
        prev:
          $ref: '#/components/schemas/PrevPage'
    AddressEmbeddedMap:       
      description: Map of embedded streets, municipalities ...
      type: object
      additionalProperties:
        anyOf:
        - $ref: '#/components/schemas/StreetEmbedded'
        - $ref: '#/components/schemas/MunicipalityEmbedded'
        - $ref: '#/components/schemas/PartOfMunicipalityEmbedded'
        - $ref: '#/components/schemas/PostalInfoEmbedded'
    AddressPosition:
      type: object
      required:
        - lambert72
        - lambert08
        - wgs84
      properties:
        lambert72:
          description: Position in Lambert72 coordinates
          type: object
          properties:
            x:
              description: x coordinate (in meters)
              type: number
              format: double
              example: 132500.5
            y:
              description: Y coordinate (in meters)
              type: number
              format: double
              example: 195000.0
        lambert08:
          description: Position in Lambert2008 coordinates
          type: object
          properties:
            x:
              description: x coordinate (in meters)
              type: number
              format: double
              example: 632497.1
            y:
              description: Y coordinate (in meters)
              type: number
              format: double
              example: 694998.2
        wgs84:
          description: Position in WGS84 (GPS) coordinates
          type: object
          properties:
            lat:
              description: x coordinate (in decimal degrees)
              type: number
              format: double
              example: 51.064882
            long:
              description: Y coordinate (in decimal degrees)
              type: number
              format: double
              example: 4.119112
        positionGeometryMethod:
          description: Method being used to assign the address
          type: string
          example: assignedByAdministrator
        positionSpecification:
          description: Type of object the address is assigned to
          type: string
          example: plot
    BestIdentifier:
      type: object
      required:
        - nameSpace
        - objectIdentifier
        - versionIdentifier
      properties:
        nameSpace:
          description: Region-specific namespace, this may or may not look like a URL, URN,... depending on the Region
          type: string
          example: https://data.vlaanderen.be/id/adres/
        objectIdentifier:
          description: Region-specific identifier (not guaranteed to be unique across Regions)
          type: string
          example: '21255'
        versionIdentifier:
          description: Version identifier, may be a timestamp or a number depending on the Region
          type: string
          example: '2014-03-19T16:59:54.467'
        minorVersionIdentifier:
          description: Minor version identifier, added by Best-framework
          type: string
          example: '2'
    Municipality:
      type: object
      required:
        - id
        - bestidentifier
        - nisCode
        - name
      properties:
        id:
          description: Identifier
          type: string
        bestidentifier:
          $ref: '#/components/schemas/BestIdentifier'
        nisCode:
          description: REFNIS code (assigned by Statbel)
          type: string
          example: '21007'
        name:
          $ref: '#/components/schemas/Name'
        status:
          $ref: '#/components/schemas/Status'
        validFrom:
          $ref: '#/components/schemas/ValidFrom'
        validTo:
          $ref: '#/components/schemas/ValidTo'
        beginLifeSpanVersion:
          $ref: '#/components/schemas/BeginLifespan'
        endLifeSpanVersion:
          $ref: '#/components/schemas/EndLifespan'
        self:
          description: Hyperlink to individual municipality
          type: string
    MunicipalityEmbedded:
      type: object
      required:
        - id
        - href
        - nisCode
        - name
      properties:
        id:
          description: Identifier
          type: string
        href:
          description: Hyperlink to individual municipality
          type: string
        nisCode:
          description: REFNIS code (assigned by Statbel)
          type: string
          example: '21007'
        name:
          $ref: '#/components/schemas/Name'
        status:
          $ref: '#/components/schemas/Status'
    MunicipalityCollection:
      type: object
      required:
        - self
        - items
        - pageSize
        - total
        - totalPages
        - first
        - last
      properties:
        self:
          description: Link to self, basically the GET query being used to obtain this result
          type: string
        items:
          description: (Possibly empty) array of results
          type: array
          items:
            $ref: '#/components/schemas/Municipality'
        pageSize:
          $ref: '#/components/schemas/PageSize'
        total:
          $ref: '#/components/schemas/Total'
        totalPages:
          $ref: '#/components/schemas/TotalPages'
        first:
          $ref: '#/components/schemas/FirstPage'
        last:
          $ref: '#/components/schemas/LastPage'
        next:
          $ref: '#/components/schemas/NextPage'
        prev:
          $ref: '#/components/schemas/PrevPage'
    PartOfMunicipality:
      type: object
      required:
        - id
        - bestidentifier
        - name
      properties:
        id:
          description: Identifier
          type: string
        bestidentifier:
          $ref: '#/components/schemas/BestIdentifier'
        name:
          $ref: '#/components/schemas/Name'
        status:
          $ref: '#/components/schemas/Status'
        validFrom:
          $ref: '#/components/schemas/ValidFrom'
        validTo:
          $ref: '#/components/schemas/ValidTo'
        beginLifeSpanVersion:
          $ref: '#/components/schemas/BeginLifespan'
        endLifeSpanVersion:
          $ref: '#/components/schemas/EndLifespan'
        self:
          description: Hyperlink to individual part of municipality
          type: string
    PartOfMunicipalityCollection:
      type: object
      required:
        - self
        - items
        - pageSize
        - total
        - totalPages
        - first
        - last
      properties:
        self:
          description: Link to self, basically the GET query being used to obtain this result
          type: string
        items:
          description: (Possibly empty) array of results
          type: array
          items:
            $ref: '#/components/schemas/PartOfMunicipality'
        pageSize:
          $ref: '#/components/schemas/PageSize'
        total:
          $ref: '#/components/schemas/Total'
        totalPages:
          $ref: '#/components/schemas/TotalPages'
        first:
          $ref: '#/components/schemas/FirstPage'
        last:
          $ref: '#/components/schemas/LastPage'
        next:
          $ref: '#/components/schemas/NextPage'
        prev:
          $ref: '#/components/schemas/PrevPage'
    PartOfMunicipalityEmbedded:
      type: object
      required:
        - id
        - href
        - name
      properties:
        id:
          description: Identifier
          type: string
        href:
          description: Hyperlink to individual part of municipality
          type: string
        name:
          $ref: '#/components/schemas/Name'
        status:
          $ref: '#/components/schemas/Status'
    PostalInfo:
      type: object
      required:
        - id
        - bestidentifier
        - postCode
      properties:
        id:
          description: Identifier
          type: string
        bestidentifier:
          $ref: '#/components/schemas/BestIdentifier'
        postCode:
          description: Postal code (assigned by bPost)
          type: string
          example: '1500'
        name:
          $ref: '#/components/schemas/Name'
        status:
          $ref: '#/components/schemas/Status'
        validFrom:
          $ref: '#/components/schemas/ValidFrom'
        validTo:
          $ref: '#/components/schemas/ValidTo'
        beginLifeSpanVersion:
          $ref: '#/components/schemas/BeginLifespan'
        endLifeSpanVersion:
          $ref: '#/components/schemas/EndLifespan'
        self:
          description: Hyperlink to individual postal info
          type: string
    PostalInfoEmbedded:
      type: object
      required:
        - id
        - href
        - postCode
      properties:
        id:
          description: Identifier
          type: string
        href:
          description: Hyperlink to individual postal info
          type: string
        postCode:
          description: Postal code (assigned by bPost)
          type: string
          example: '1500'
        name:
          $ref: '#/components/schemas/Name'
        status:
          $ref: '#/components/schemas/Status'
    PostalInfoCollection:
      type: object
      required:
        - self
        - items
        - pageSize
        - total
        - totalPages
        - first
        - last
      properties:
        self:
          description: Link to self, basically the GET query being used to obtain this result
          type: string
        items:
          description: (Possibly empty) array of results
          type: array
          items:
            $ref: '#/components/schemas/PostalInfo'
        pageSize:
          $ref: '#/components/schemas/PageSize'
        total:
          $ref: '#/components/schemas/Total'
        totalPages:
          $ref: '#/components/schemas/TotalPages'
        first:
          $ref: '#/components/schemas/FirstPage'
        last:
          $ref: '#/components/schemas/LastPage'
        next:
          $ref: '#/components/schemas/NextPage'
        prev:
          $ref: '#/components/schemas/PrevPage'
    Status:
      type: string
      default: current
      enum:
        - any
        - current
        - proposed
        - reserved
        - retired
        - rejected
      example: current
    Street:
      type: object
      required:
        - id
        - bestidentifier
        - name
      properties:
        id:
          description: Identifier
          type: string
        bestidentifier:
          $ref: '#/components/schemas/BestIdentifier'
        name:
          $ref: '#/components/schemas/Name'
        homonymAddition:
          description: Additional string to differentiate between similar street names
          type: string
        streetNameType:
          description: Type of the street
          type: string
          enum:
           - hamlet
           - streetname
          example: streetname
        status:
          $ref: '#/components/schemas/Status'
        validFrom:
          $ref: '#/components/schemas/ValidFrom'
        validTo:
          $ref: '#/components/schemas/ValidTo'
        beginLifeSpanVersion:
          $ref: '#/components/schemas/BeginLifespan'
        endLifeSpanVersion:
          $ref: '#/components/schemas/EndLifespan'
        isAssignedBy:
          oneOf:
            - $ref: '#/components/schemas/ObjectReference'
            - $ref: '#/components/schemas/MunicipalityEmbedded'
        embedded:
          $ref: '#/components/schemas/StreetEmbeddedMap'            
        self:
          description: Hyperlink to individual street
          type: string
    StreetEmbeddedMap:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/MunicipalityEmbedded'
    StreetEmbedded:
      type: object
      required:
        - id
        - href
        - name
      properties:
        id:
          description: Identifier
          type: string
        href:
          description: Hyperlink to individual street
          type: string
        name:
          $ref: '#/components/schemas/Name'
        homonymAddition:
          description: Additional string to differentiate between similar street names
          type: string
        streetNameType:
          description: Type of the street
          type: string
          enum:
           - hamlet
           - streetname
          example: streetname
    StreetCollection:
      type: object
      required:
        - self
        - items
        - pageSize
        - total
        - totalPages
        - first
        - last
      properties:
        self:
          description: Link to self, basically the GET query being used to obtain this result
          type: string
        items:
          description: (Possibly empty) array of results
          type: array
          items:
            $ref: '#/components/schemas/Street'
        embedded:
          $ref: '#/components/schemas/StreetEmbeddedMap'   
        pageSize:
          $ref: '#/components/schemas/PageSize'
        total:
          $ref: '#/components/schemas/Total'
        totalPages:
          $ref: '#/components/schemas/TotalPages'
        first:
          $ref: '#/components/schemas/FirstPage'
        next:
          $ref: '#/components/schemas/NextPage'
        last:
          $ref: '#/components/schemas/LastPage'
        prev:
          $ref: '#/components/schemas/PrevPage'
    FirstPage:
      description: Link to the first page in the collection
      type: string
      format: url
    LastPage:
      description: Link to the last page in the collection
      type: string
      format: url
    NextPage:
      description: Link to the next page in the collection, if any
      type: string
      format: url
    PrevPage:
      description: Link to the previous page in the collection, if any
      type: string
      format: url
    PageSize:
      description: Maximum number of results on any given page
      type: number
      format: uint32
      minimum: 0
      example: 100
    Total:
      description: Total number of results, might be zero
      type: number
      format: uint32
      minimum: 0
      example: 2571
    TotalPages:
      description: Total number of pages
      type: number
      format: uint32
      minimum: 0
      example: 15
    BadRequestResponse:
      description: Bad Request object
      type: object
      properties:
        type:
          type: string
          format: uri
          description: A URN that identifies the problem type
          example: 'urn:problem-type:belgif:badRequest'
        href:
          type: string
          format: uri
          description: An absolute URI that, when dereferenced, provides human readable documentation for the problem type (e.g. using HTML).
          example: 'https://www.belgif.be/specification/rest/api-guide/problems/badRequest.html'
        title:
          type: string
          description: A short summary of the problem type, in English.
          example: Bad Request
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          default: 400
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
          example: Bad request
    UnauthorizedResponse:
      description: No (or invalid/expired) access token
      type: object
      properties:
        type:
          type: string
          format: uri
          description: A URN that identifies the problem type
          example: 'urn:problem-type:belgif:noAccessToken'
        href:
          type: string
          format: uri
          description: An absolute URI that, when dereferenced, provides human readable documentation for the problem type (e.g. using HTML).
          example: 'https://www.belgif.be/specification/rest/api-guide/problems/noAccessToken.html'
        title:
          type: string
          description: A short summary of the problem type, in English.
          example: Unauthorized
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          default: 401
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
          example: Unauthorized
    NotFoundResponse:
      description: Not Found object
      type: object
      properties:
        type:
          type: string
          format: uri
          description: A URN that identifies the problem type
          example: 'urn:problem-type:belgif:resourceNotFound'
        href:
          type: string
          format: uri
          description: An absolute URI that, when dereferenced, provides human readable documentation for the problem type (e.g. using HTML).
          example: 'https://www.belgif.be/specification/rest/api-guide/problems/resourceNotFound.html'
        title:
          type: string
          description: A short summary of the problem type, in English.
          example: Resource is not found
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          default: 404
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
          example: Resource is not found
    ProblemResponse:
      description: A Problem Details object (RFC 7807)
      type: object
      properties:
        type:
          type: string
          format: uri
          description: A URN that identifies the problem type
          example: 'urn:problem-type:belgif:internalServerError'
        href:
          type: string
          format: uri
          description: An absolute URI that, when dereferenced, provides human readable documentation for the problem type (e.g. using HTML).
          example: 'https://www.belgif.be/specification/rest/api-guide/problems/internalServerError.html'
        title:
          type: string
          description: A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized).
          example: Internal Server Error
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 400
          maximum: 600
          exclusiveMaximum: true
          example: 500
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
          example: Something went wrong on the server-side
    ValidFrom:
      description: Valid from date (local time)
      type: string
      format: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,9})?)?$
      example: '2016-01-01T00:00:00'
    ValidTo:
      description: Valid till date (local time)
      type: string
      format: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,9})?)?$
      example: '2019-01-01T00:00:00'
    BeginLifespan:
      description: Begin of lifespan (local time)
      type: string
      format: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,9})?)?$
      example: '2016-01-01T00:00:00'
    EndLifespan:
      description: End of lifespan (local time)
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,9})?)?$
      example: '2019-01-01T00:00:00'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://public.int.fedservices.be/api/oauth2/token
          scopes: {}