woz-api-nl Account API

openapi: 3.2.0
info:
  title: Wozapi Account API
  description: 'De WOZ API die je zelf regelt. WOZ-waarden, BAG-adresgegevens met bouwjaar en oppervlakte, WOZ-object en kadastrale percelen uit 1 endpoint. Met `energielabel=true` ook het geregistreerde energielabel (EP-Online van RVO), zonder extra credit.


    **Base URL:** `https://woz-api.nl`


    **Authenticatie:** stuur je key mee als header `X-Api-Key: {key}` of als `Authorization: ApiKey {key}`. Een key maak je aan onder API sleutels. Een sleutel hoort in een header, nooit in een URL.


    **Voor softwareleveranciers (OAuth-koppeling):** laat je klant zijn eigen Wozapi-account koppelen via OAuth 2.0 (authorization code met PKCE) en stuur diens access token mee als `Authorization: Bearer {token}`. De credits gaan dan van het account van je klant af. Scopes: `woz.lookup` en `account.saldo`. Discovery: `/.well-known/openid-configuration`. Uitleg en aanvraag: woz-api.nl/woz-api-koppeling.


    **Credits:** 1 credit is 1 uniek adres. Hetzelfde adres binnen 7 dagen opnieuw opvragen kost geen extra credit; dat is een kortingsregel en geen cache, de request wordt wel echt uitgevoerd. Een opvraging die op een fout eindigt (4xx of 5xx) kost niets, en een antwoord zonder WOZ-waarden (een lege `woz`) ook niet. Een nieuw account krijgt 10 gratis credits. Het resterende saldo staat in de response-header `X-Credits-Remaining` en is ook op te vragen via `GET /Api/Credits`. Is het saldo op, dan volgt 402 met code `InsufficientCredits`.


    **Zonder account:** vraag een gratis proefsleutel aan met `POST /Api/Proef` (5 unieke adressen, 10 met het e-mailadres van de gebruiker) en stuur hem mee als `X-Api-Key`. Zonder sleutel geeft de API 401 met code `SleutelOntbreekt`; een verbruikte proef geeft 402 met code `ProefVerbruikt`.


    **Een hele lijst:** `POST /Api/Lijst` met de adressen geeft een gratis proef van 5 adressen, de prijs voor de hele lijst en een betaalpagina voor de gebruiker; na betaling de rijen en het bestand.


    **AI-assistenten:** een MCP-server op `https://woz-api.nl/Api/Mcp`, en uitleg voor agents op woz-api.nl/voor-ai-agents.


    **Foutvorm:** elke fout geeft `{ fout, code, status, detail, traceId }` terug, zie het schema ApiFoutResponse. Dat geldt ook voor een 400 door modelvalidatie; `detail` bevat dan per veld de meldingen. Match in code op `code`, niet op de tekst in `fout`. Veelvoorkomende codes: `InvalidInput` (400), `Unauthorized` (401), `InsufficientCredits` (402), `AddressNotFound` (404), `PdokLookupFailed` (502) en `UpstreamUnavailable` (503). Een 502 of 503 kost niets; probeer het opnieuw, bij een 503 na het aantal seconden uit de header `Retry-After`, en sla het adres niet over.


    **Geen WOZ-waarde:** alleen van woningen is de WOZ-waarde openbaar. Bestaat het adres maar is er geen openbare waarde, bijvoorbeeld bij een kantoor of kerk, dan krijg je een 200 met een lege `woz`, `huidigeWaarde: null` en in `wozStatus` de reden: `geen_woning` als het pand volgens de BAG geen woonfunctie heeft, anders `geen_waarde`. Dat is een antwoord en geen storing: opnieuw proberen verandert niets, en het kost geen credit. Een storing geeft altijd een 502 of 503.


    **Voorbeeld:**


    ```

    curl "https://woz-api.nl/Api/Adres?adres=Spuistraat%2036C,%201012TT%20Amsterdam" \

    -H "X-Api-Key: JOUW_API_KEY"

    ```'
  termsOfService: https://woz-api.nl/terms
  contact:
    name: Wozapi
    url: https://woz-api.nl/
    email: info@woz-api.nl
  version: v1
servers:
- url: https://woz-api.nl
  description: Productie
security:
- ApiKey: []
tags:
- name: Account
  description: Je creditsaldo uitlezen zonder een credit te verbruiken.
paths:
  /Api/Credits:
    get:
      tags:
      - Account
      summary: Huidig creditsaldo bij de meegestuurde API-key
      description: 'Kost zelf geen credit. Handig om vooraf te bewaken dat je niet tegen een 402 aanloopt,

        bijvoorbeeld voor een batch. Tijdens een reeks lookups kun je in plaats hiervan de

        response-header X-Credits-Remaining uitlezen, die na elke geslaagde call meekomt.


        Dit endpoint vereist een key: anoniem toegang heeft geen saldo.'
      responses:
        '200':
          description: Het saldo dat bij deze key hoort.
          headers:
            X-Credits-Remaining:
              description: Aantal resterende credits na deze request. Alleen aanwezig bij requests met een geldige accountsessie of API-key.
              schema:
                type: integer
                format: int32
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/CreditsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/CreditsResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/CreditsResponse'
        '401':
          description: API-key ontbreekt of is ongeldig.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ApiFoutResponse'
      operationId: getApiCredits
      x-operation-id-source: derived
components:
  schemas:
    ApiFoutResponse:
      type: object
      properties:
        fout:
          type:
          - string
          - 'null'
          description: Foutmelding in het Nederlands, bedoeld om te tonen aan een eindgebruiker.
          example: Ongeldige API-key.
        code:
          type:
          - string
          - 'null'
          description: 'Stabiele foutcode om in code op te matchen. Niet elke fout heeft er een; bij een

            onverwachte fout is dit veld null.'
          example: Unauthorized
        status:
          type: integer
          description: De HTTP-statuscode, ook in de body zodat loggen zonder response-object werkt.
          format: int32
          example: 401
        detail:
          description: 'Extra toelichting waar die bestaat, anders null. Dit is soms een tekst en soms een

            object (bijvoorbeeld met de gezochte term en een hint), dus lees het als vrije JSON.'
        traceId:
          type:
          - string
          - 'null'
          description: Correlatie-id van de request. Vermeld dit bij een supportvraag.
          example: 0HN7GK2P3QJ1M:00000003
      additionalProperties: false
      description: 'De foutrespons die de API werkelijk teruggeeft. Bestaat omdat de OpenAPI-spec bij 400, 401,

        402 en 404 naar ProblemDetails verwees, terwijl

        WozApi.Middleware.ErrorHandlingMiddleware een heel andere vorm stuurt. Wie op de

        documentatie bouwde, parseerde dus elke fout verkeerd.'
    TegoedInfo:
      type: object
      properties:
        soort:
          type:
          - string
          - 'null'
          description: '"proef" zolang de sleutel aan geen account hangt, "credits" als hij van een account is.'
          example: proef
        limiet:
          type:
          - integer
          - 'null'
          description: Unieke adressen die deze proef in totaal mag; leeg bij credits.
          format: int32
          example: 5
        gebruikt:
          type:
          - integer
          - 'null'
          description: Unieke adressen die al gebruikt zijn; leeg bij credits.
          format: int32
          example: 1
        resterend:
          type: integer
          description: 'Wat er nog kan: adressen in de proef, of credits op het account.'
          format: int32
          example: 4
        verlooptOp:
          type:
          - string
          - 'null'
          description: Wanneer een proefsleutel zonder account vervalt.
          format: date-time
      additionalProperties: false
      description: Het tegoed van een proefsleutel of van een account dat een AI-assistent aanmaakte.
    CreditsResponse:
      type: object
      properties:
        credits:
          type: integer
          format: int32
        tegoed:
          $ref: '#/components/schemas/TegoedInfo'
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: apiKey
      description: 'Gebruik je API key via header: X-Api-Key: {key} of Authorization: ApiKey {key}'
      name: X-Api-Key
      in: header
    OAuth2:
      type: oauth2
      description: 'OAuth-koppeling voor softwareleveranciers: authorization code met PKCE. Je klant koppelt zijn eigen Wozapi-account; credits gaan van diens saldo af.'
      flows:
        authorizationCode:
          authorizationUrl: https://woz-api.nl/connect/authorize
          tokenUrl: https://woz-api.nl/connect/token
          scopes:
            woz.lookup: WOZ-gegevens opvragen op de credits van de gekoppelde klant
            account.saldo: Creditsaldo van de gekoppelde klant lezen