openapi: 3.1.0
info:
  title: BRP bewoning
  description: |
    API voor het raadplegen van de (historische) bewoning van een adres.
  version: 2.1.0
  contact:
    url: https://github.com/BRP-API/Haal-Centraal-BRP-bewoning
  license:
    name: European Union Public License, version 1.2 (EUPL-1.2)
    url: https://eupl.eu/1.2/nl/
tags:
  - name: Bewoning
externalDocs:
  description: Haal Centraal BRP bewoning website
  url: https://brp-api.github.io/Haal-Centraal-BRP-bewoning/
paths:
  /bewoningen:
    post:
      summary: Raadplegen van bewoningen
      description: |
        Met de API kun je raadplegen:

        **Bewoning:**
        welke personen (bewoners) een adresseerbaar object bewoonden op een opgegeven moment (peildatum) of
        welke samenstellingen van personen een adresseerbaar object bewoonden in een opgegeven periode.
      operationId: Bewoningen
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/BewoningenQuery'
      responses:
        '200':
          description: |
            Zoekactie geslaagd
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BewoningenQueryResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '501':
          $ref: '#/components/responses/501'
        '503':
          $ref: '#/components/responses/503'
        default:
          $ref: '#/components/responses/500'
      tags:
        - Bewoning
components:
  schemas:
    BewoningenQuery:
      type: object
      required:
        - type
      discriminator:
        propertyName: type
        mapping:
          BewoningMetPeildatum: '#/components/schemas/BewoningMetPeildatum'
          BewoningMetPeriode: '#/components/schemas/BewoningMetPeriode'
      properties:
        type:
          type: string
      example:
        type: BewoningMetPeriode
        datumVan: '2023-11-19'
        datumTot: '2024-01-27'
        adresseerbaarObjectIdentificatie: '0599010370005001'
    BewoningMetPeildatum:
      required:
        - peildatum
        - adresseerbaarObjectIdentificatie
      allOf:
        - $ref: '#/components/schemas/BewoningenQuery'
        - type: object
          properties:
            peildatum:
              $ref: '#/components/schemas/DatumFilter'
              description: |
                de datum waarover de bewoning wordt opgevraagd.
            adresseerbaarObjectIdentificatie:
              $ref: '#/components/schemas/AdresseerbaarObjectIdentificatieFilter'
              description: |
                De identificatie van het adresseerbaar object waarover de bewoning wordt gevraagd.
    BewoningMetPeriode:
      required:
        - datumVan
        - datumTot
        - adresseerbaarObjectIdentificatie
      allOf:
        - $ref: '#/components/schemas/BewoningenQuery'
        - type: object
          properties:
            datumVan:
              $ref: '#/components/schemas/DatumFilter'
              description: |
                de begindatum van de periode waarover de bewoning wordt opgevraagd.
            datumTot:
              $ref: '#/components/schemas/DatumFilter'
              description: |
                de einddatum van de periode waarover de bewoning wordt opgevraagd.
            adresseerbaarObjectIdentificatie:
              $ref: '#/components/schemas/AdresseerbaarObjectIdentificatieFilter'
              description: |
                De identificatie van het adresseerbaar object waarover de bewoning wordt gevraagd.
    BewoningenQueryResponse:
      type: object
      properties:
        bewoningen:
          type: array
          items:
            $ref: '#/components/schemas/Bewoning'
      example:
        bewoningen:
          - adresseerbaarObjectIdentificatie: '0599010370005001'
            periode:
              datumVan: '2023-11-19'
              datumTot: '2024-01-01'
            bewoners:
              - burgerservicenummer: '999997968'
                geheimhoudingPersoonsgegevens: true
              - burgerservicenummer: '999990524'
                naam:
                  volledigeNaam: Pieter Jan de Vries
                geboorte:
                  datum:
                    type: Datum
                    langFormaat: 1 juli 1984
                    datum: '1984-07-01'
            mogelijkeBewoners: []
          - adresseerbaarObjectIdentificatie: '0599010370005001'
            periode:
              datumVan: '2024-01-01'
              datumTot: '2024-01-27'
            bewoners:
              - burgerservicenummer: '999997968'
                geheimhoudingPersoonsgegevens: true
            mogelijkeBewoners:
              - burgerservicenummer: '999990524'
    DatumFilter:
      type: string
      format: date
      example: '1964-09-24'
    AdresseerbaarObjectIdentificatieFilter:
      type: string
      pattern: ^(?!0{16})[0-9]{16}$
      description: |
        De identificatiecode van een adresseerbaar object uitgezonderd de standaardwaarde (0000000000000000)
      example: '0226010000038820'
    Foutbericht:
      type: object
      description: Terugmelding bij een fout. JSON representatie in lijn met [RFC7807](https://tools.ietf.org/html/rfc7807).
      properties:
        type:
          description: Link naar meer informatie over deze fout
          type: string
          format: uri
        title:
          description: Beschrijving van de fout
          type: string
          pattern: ^[a-zA-Z0-9À-ž \.\-]{1,80}$
        status:
          type: integer
          minimum: 100
          maximum: 600
          description: Http status code
        detail:
          description: Details over de fout
          type: string
          pattern: ^[a-zA-Z0-9À-ž \.\-\(\),]{1,200}$
        instance:
          description: Uri van de aanroep die de fout heeft veroorzaakt
          type: string
          format: uri
        code:
          description: Systeemcode die het type fout aangeeft
          type: string
          pattern: ^[a-zA-Z0-9]{1,25}$
    AdresseerbaarObjectIdentificatie:
      type: string
      pattern: ^[0-9]{16}$
      description: |
        De identificatiecode van een adresseerbaar object.
      example: '0226010000038820'
    Datum:
      type: string
      format: date
      example: '1964-09-24'
      description: |
        Datum conform ISO-8601
    Periode:
      type: object
      properties:
        datumVan:
          allOf:
            - $ref: '#/components/schemas/Datum'
              description: |
                De begindatum van de periode.
            - example: '2020-01-01'
        datumTot:
          allOf:
            - $ref: '#/components/schemas/Datum'
              description: |
                De einddatum van de periode.
            - example: '2021-01-01'
    Burgerservicenummer:
      type: string
      pattern: ^[0-9]{9}$
      example: '555555021'
    GeheimhoudingPersoonsgegevens:
      description: |
        Indicatie dat persoonsgegevens niet mogen worden verstrekt aan derden / maatschappelijke instellingen.
      type: boolean
    InOnderzoek:
      type: boolean
      description: |
        Geeft aan dat de verblijfplaats in onderzoek is.
    VolledigeNaam:
      type: string
      pattern: ^[a-zA-Z0-9À-ž \.\-\']{1,450}$
      description: |
        Combinatie van predicaat, voornamen, adellijke titel, voorvoegsels en geslachtsnaam, zonder toevoeging van een eventuele partnernaam.
      example: Pieter Jan de Vries
    Naam:
      type: object
      properties:
        volledigeNaam:
          $ref: '#/components/schemas/VolledigeNaam'
    AbstractDatum:
      type: object
      required:
        - type
        - langFormaat
      properties:
        type:
          type: string
        langFormaat:
          type: string
          pattern: ^[a-z0-9 ]{1,17}$
      discriminator:
        propertyName: type
        mapping:
          Datum: '#/components/schemas/VolledigeDatum'
          DatumOnbekend: '#/components/schemas/DatumOnbekend'
          JaarDatum: '#/components/schemas/JaarDatum'
          JaarMaandDatum: '#/components/schemas/JaarMaandDatum'
      example:
        type: Datum
        datum: '2018-07-01'
        langFormaat: 1 juli 2018
    VolledigeDatum:
      description: Datum conform iso8601
      allOf:
        - $ref: '#/components/schemas/AbstractDatum'
        - type: object
          properties:
            datum:
              type: string
              format: date
      required:
        - datum
      example:
        type: Datum
        datum: '2018-07-01'
        langFormaat: 1 juli 2018
    DatumOnbekend:
      description: representatie voor een volledig onbekend datum
      allOf:
        - $ref: '#/components/schemas/AbstractDatum'
        - type: object
          properties:
            onbekend:
              type: boolean
              default: true
      required:
        - onbekend
      example:
        type: DatumOnbekend
        onbekend: true
        langFormaat: onbekend
    Jaar:
      type: integer
      format: int32
      minimum: 1
      maximum: 9999
    JaarDatum:
      description: representatie voor een datum waarvan maand en dag onbekend zijn
      allOf:
        - $ref: '#/components/schemas/AbstractDatum'
        - type: object
          properties:
            jaar:
              $ref: '#/components/schemas/Jaar'
      required:
        - jaar
      example:
        type: JaarDatum
        jaar: 2018
        langFormaat: 2018
    Maand:
      type: integer
      format: int32
      minimum: 1
      maximum: 12
    JaarMaandDatum:
      description: representatie voor een datum waarvan de dag onbekend is
      allOf:
        - $ref: '#/components/schemas/AbstractDatum'
        - type: object
          properties:
            jaar:
              $ref: '#/components/schemas/Jaar'
            maand:
              $ref: '#/components/schemas/Maand'
      required:
        - jaar
        - maand
      example:
        type: JaarMaandDatum
        jaar: 2018
        maand: 7
        langFormaat: juli 2018
    GeboorteBasis:
      type: object
      properties:
        datum:
          $ref: '#/components/schemas/AbstractDatum'
          description: |
            Datum waarop de persoon is geboren.
    Bewoner:
      type: object
      properties:
        burgerservicenummer:
          $ref: '#/components/schemas/Burgerservicenummer'
        geheimhoudingPersoonsgegevens:
          $ref: '#/components/schemas/GeheimhoudingPersoonsgegevens'
        inOnderzoek:
          $ref: '#/components/schemas/InOnderzoek'
        naam:
          $ref: '#/components/schemas/Naam'
        geboorte:
          $ref: '#/components/schemas/GeboorteBasis'
    Bewoning:
      description: |
        Een bewoning geeft aan welke personen in een periode (mogelijk) op een adresseerbaar object staan ingeschreven.

        Een persoon is een mogelijke bewoner als niet met zekerheid kan worden bepaald of de persoon in de bewoningperiode op het adresseerbaar object staat/stond ingeschreven.
        Dit is het geval als de datum aanvang of de datum einde van de inschrijving geheel of deels onbekend is, en de onzekerheidsperiode overlapt de bewoningperiode.

        Wanneer een bewoning in totaal meer dan 100 bewoners en/of mogelijke bewoners heeft, wordt het **indicatieVeelBewoners** veld geleverd.
      type: object
      properties:
        adresseerbaarObjectIdentificatie:
          $ref: '#/components/schemas/AdresseerbaarObjectIdentificatie'
        periode:
          $ref: '#/components/schemas/Periode'
        bewoners:
          type: array
          description: |
            De personen die in de bewoning periode staan ingeschreven op het adresseerbaar object.
          minItems: 0
          maxItems: 100
          items:
            $ref: '#/components/schemas/Bewoner'
        mogelijkeBewoners:
          type: array
          description: |
            De personen die in de bewoning periode mogelijk staan ingeschreven op het adresseerbaar object.
          minItems: 0
          maxItems: 100
          items:
            $ref: '#/components/schemas/Bewoner'
        indicatieVeelBewoners:
          type: boolean
          description: |
            Geeft aan dat de bewoning in totaal meer dan 100 bewoners en/of mogelijke bewoners heeft.
    InvalidParam:
      type: object
      description: Details over fouten in opgegeven parameters
      properties:
        type:
          type: string
          format: uri
          example: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1
        name:
          description: Naam van de parameter
          type: string
          pattern: ^[a-zA-Z0-9\._]{1,30}$
          example: huisnummer
        code:
          description: Systeemcode die het type fout aangeeft
          type: string
          pattern: ^[a-zA-Z0-9]{1,25}$
          example: integer
        reason:
          description: Beschrijving van de fout op de parameterwaarde
          type: string
          pattern: ^[a-zA-Z0-9\., ]{1,80}$
          example: Waarde is geen geldig getal.
    BadRequestFoutbericht:
      allOf:
        - $ref: '#/components/schemas/Foutbericht'
        - type: object
          properties:
            invalidParams:
              description: |
                Foutmelding per fout in een parameter. Alle gevonden fouten worden één keer teruggemeld.
              type: array
              items:
                $ref: '#/components/schemas/InvalidParam'
  responses:
    '400':
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BadRequestFoutbericht'
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1
            title: Ten minste één parameter moet worden opgegeven.
            status: 400
            detail: The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modification.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: paramsRequired
            invalidParams:
              - type: https://www.vng.nl/realisatie/api/validaties/integer
                name: huisnummer
                code: integer
                reason: Waarde is geen geldig getal.
    '401':
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Foutbericht'
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2
            title: Niet correct geauthenticeerd.
            status: 401
            detail: The request requires user authentication. The response MUST include a WWW-Authenticate header field (section 14.47) containing a challenge applicable to the requested resource.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: authentication
    '403':
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Foutbericht'
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4
            title: U bent niet geautoriseerd voor deze operatie.
            status: 403
            detail: The server understood the request, but is refusing to fulfill it.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: autorisation
    '406':
      description: Not Acceptable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Foutbericht'
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7
            title: Gevraagde contenttype wordt niet ondersteund.
            status: 406
            detail: The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to thr accept headers sent in the request
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: notAcceptable
    '429':
      description: Too Many Requests
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Foutbericht'
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
            title: Too many request
            status: 429
            detail: The user has sent too many requests in a given amount of time (rate limiting).
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: tooManyRequests
    '500':
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Foutbericht'
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1
            title: Interne server fout.
            status: 500
            detail: The server encountered an unexpected condition which prevented it from fulfilling the request.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: serverError
    '501':
      description: Not Implemented
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Foutbericht'
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2
            title: Not Implemented
            status: 501
            detail: The server does not support the functionality required to fulfill the request.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: notImplemented
    '503':
      description: Service Unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Foutbericht'
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4
            title: Bronservice BRP is tijdelijk niet beschikbaar.
            status: 503
            detail: The service is currently unable to handle the request due to a temporary overloading or maintenance of the server.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: notAvailable