{ "openapi": "3.1.0", "info": { "title": "BAG API suite", "version": "0.0.1", "description": "De BAG API geeft toegang tot de Basisregistratie Adressen en Gebouwen (BAG) van het Kadaster. Kies uit drie endpoints: volledige adresgegevens, adres-autocomplete of een lookup op BAG-ID.\n\n## Authentication\n\nAll API endpoints require authentication. Include your API key in every request using **one** of the following methods:\n\n**Option 1 \u2014 X-Api-Key header (recommended)**\n```\nX-Api-Key: ga_live_xxxxxxxxxxxxxxxxxxxx\n```\n\n**Option 2 \u2014 Bearer token**\n```\nAuthorization: Bearer ga_live_xxxxxxxxxxxxxxxxxxxx\n```\n\nYou can generate and manage API keys in your [dashboard](https://getapi.nl/dashboard).\n\n## AI & Agent Payments (x402)\n\nSome endpoints support direct payments for AI agents via the **x402** protocol (https://www.x402.org).\nNo API key or account is needed. Send a normal request without key;\nthe server will respond with **HTTP 402** and a `PAYMENT-REQUIRED` header:\n\n```\nPAYMENT-REQUIRED: \n```\n\nThis base64 string contains, among other things, `network`, `asset`, `amount`, and `payTo`. \nYour agent signs an EIP-3009 *transferWithAuthorization* for the specified `amount` of USDC to that `payTo` address, \nencodes the signature as base64, and resubmits the request with:\n\n```\nPAYMENT-SIGNATURE: \n```\n\nThe server verifies the signature via a facilitator, provides the data, and settles the payment on-chain. \nThe success response includes a `PAYMENT-RESPONSE` header containing the transaction information. \nA one-time `nonce` prevents replay attacks. Payments are made in USDC on **Base**; \nthe price is determined by the `credit_cost` of the endpoint.", "contact": { "email": "info@wdnoord.nl" }, "x-guidance": "GetAPI.nl is een Nederlandse API-platform voor lookups en validaties (postcode,\nadres, kenteken, BTW, e-mail, KVK, IBAN, energiemaatwerk, overheidsdata). Elke\nendpoint accepteert een API key via de X-Api-Key header of Authorization:\nBearer .\n\nSommige endpoints zijn ook direct betaalbaar voor AI-agents via het x402-protocol\n(https://www.x402.org) zonder account of API key: stuur een verzoek zonder key,\nde server antwoordt met HTTP 402 en een PAYMENT-REQUIRED header (base64 JSON met\nnetwork, asset, amount, payTo). Teken daarna een EIP-3009 transferWithAuthorization\nvoor het gevraagde bedrag in USDC op Base en hertrail met een PAYMENT-SIGNATURE\nheader. De server verifieert, levert de data en settleert on-chain.\n\nTips voor agents:\n- Lees eerst de PAYMENT-REQUIRED header van een 402-antwoord; die is leidend.\n- Geef altijd de exact door de server gevraagde parameters mee.\n- Een endpoint met een \"x-payment-info\" blok vereist betaling voor gebruik." }, "servers": [ { "url": "https://api.getapi.nl", "description": "GetAPI" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "paths": { "/v1/kadaster/bag/address": { "get": { "operationId": "kadaster.bag.address", "description": "Returns full BAG address data for a Dutch address, including BAG IDs,\nusage purposes, surface area, build year, status, and GPS coordinates.\n\nData is sourced from the PDOK BAG open API (Landelijke Voorziening BAG).\n\nResults are cached for 24 hours. The upstream timeout is 8 seconds;\nif PDOK is unavailable the endpoint returns HTTP 503.\n\nSource: [PDOK BAG](https://api.pdok.nl/lv/bag/open-api/v1_5)", "summary": "Address lookup by postcode and house number", "tags": [ "BAG \u2013 Basisregistratie Adressen en Gebouwen", "BagAdres" ], "parameters": [ { "name": "postcode", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{3}\\s?[A-Za-z]{2}$" } }, { "name": "house_number", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 99999 } }, { "name": "house_letter", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{1}$" } }, { "name": "house_number_addition", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z0-9]{1,4}$", "maxLength": 4 } } ], "responses": { "200": { "description": "Address found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "found": true, "address": { "bag_nummeraanduiding_id": "0363200000218908", "bag_verblijfsobject_id": "0363010000218908", "bag_pand_ids": [ "0363100012165277" ], "bag_openbare_ruimte_id": "0363300000006316", "bag_woonplaats_id": "3594", "street": "Damrak", "short_name": "Damrak", "house_number": 1, "house_letter": null, "house_number_addition": null, "postcode": "1012LG", "city": "Amsterdam", "municipality": "Amsterdam", "address_line": "Damrak 1", "address_line_postal": "1012 LG AMSTERDAM", "usage_purposes": [ "retail" ], "surface_area_m2": 312, "build_year": 1900, "status": "in_use", "type": "residence", "is_secondary_address": false, "is_observed": false, "in_investigation": null, "document_date": "2019-11-22", "document_number": "19SZ2048", "secondary_address_ids": [], "occurrence": null, "lat": 52.3745, "lon": 4.8986 } } ], "properties": { "found": { "type": "boolean" }, "address": { "type": "object", "properties": { "bag_nummeraanduiding_id": { "type": "string" }, "bag_verblijfsobject_id": { "type": "string" }, "bag_pand_ids": { "type": "array", "items": { "type": "string" } }, "bag_openbare_ruimte_id": { "type": "string" }, "bag_woonplaats_id": { "type": "string" }, "street": { "type": [ "string", "null" ] }, "short_name": { "type": [ "string", "null" ] }, "house_number": { "type": "integer" }, "house_letter": { "type": [ "string", "null" ] }, "house_number_addition": { "type": [ "string", "null" ] }, "postcode": { "type": "string" }, "city": { "type": "string" }, "municipality": { "type": "string" }, "address_line": { "type": "string" }, "address_line_postal": { "type": "string" }, "usage_purposes": { "type": "array", "items": { "type": "string" } }, "surface_area_m2": { "type": [ "integer", "null" ] }, "build_year": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "is_secondary_address": { "type": "boolean" }, "is_observed": { "type": [ "boolean", "null" ] }, "in_investigation": [], "document_date": { "type": [ "string", "null" ] }, "document_number": { "type": [ "string", "null" ] }, "secondary_address_ids": { "type": "array", "items": { "type": "string" } }, "occurrence": [], "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] } }, "required": [ "bag_nummeraanduiding_id", "bag_verblijfsobject_id", "bag_pand_ids", "bag_openbare_ruimte_id", "bag_woonplaats_id", "street", "short_name", "house_number", "house_letter", "house_number_addition", "postcode", "city", "municipality", "address_line", "address_line_postal", "usage_purposes", "surface_area_m2", "build_year", "status", "type", "is_secondary_address", "is_observed", "in_investigation", "document_date", "document_number", "secondary_address_ids", "occurrence", "lat", "lon" ] } }, "required": [ "found", "address" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "description": "Address not found in BAG", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "found": false, "address": null } ], "properties": { "found": { "type": "boolean" }, "address": { "type": "null" } }, "required": [ "found", "address" ] } } } }, "503": { "description": "Upstream source (PDOK) unavailable or timed out (8 s)", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "found": false, "address": null } ], "properties": { "found": { "type": "boolean" }, "address": { "type": "null" } }, "required": [ "found", "address" ] } } } }, "402": { "description": "Payment Required" } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] } } }, "/v1/kadaster/bag/address-suggest": { "get": { "operationId": "kadaster.bag.address-suggest", "description": "Returns address suggestions for autocomplete functionality based on a partial query.\nUseful for implementing address autocomplete in forms. Returns up to 10 suggestions\nwith full address details and BAG identifiers.\n\nResults are cached for 1 hour.", "summary": "Address autocomplete suggestions", "tags": [ "BAG \u2013 Basisregistratie Adressen en Gebouwen", "AddressSuggest" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 25 } } ], "responses": { "200": { "description": "Address suggestions found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "suggestions": [ { "id": "adr-1234567890123456", "label": "Damrak 1, 1012LG Amsterdam", "type": "adres", "nummeraanduiding_id": "1234567890123456", "verblijfsobject_id": "1234567890123456", "postcode": "1012LG", "house_number": 1 }, { "id": "adr-1234567890123457", "label": "Damrak 2, 1012LG Amsterdam", "type": "adres", "nummeraanduiding_id": "1234567890123457", "verblijfsobject_id": "1234567890123457", "postcode": "1012LG", "house_number": 2 } ] } ], "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "nummeraanduiding_id": { "type": [ "string", "null" ] }, "verblijfsobject_id": { "type": [ "string", "null" ] }, "postcode": { "type": [ "string", "null" ] }, "house_number": { "type": [ "integer", "null" ] } }, "required": [ "id", "label", "type", "nummeraanduiding_id", "verblijfsobject_id", "postcode", "house_number" ] } } }, "required": [ "suggestions" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "402": { "description": "Payment Required" } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] } } }, "/v1/kadaster/bag/id": { "get": { "operationId": "kadaster.bag.id", "description": "Returns full BAG address data for a given BAG nummeraanduiding ID.\nThe nummeraanduiding ID is a 16-digit identifier from the BAG register.\n\nData is sourced from the PDOK BAG open API (Landelijke Voorziening BAG).\n\nResults are cached for 24 hours. The upstream timeout is 8 seconds;\nif PDOK is unavailable the endpoint returns HTTP 503.\n\nSource: [PDOK BAG](https://api.pdok.nl/lv/bag/open-api/v1_5)", "summary": "Address lookup by nummeraanduiding ID", "tags": [ "BAG \u2013 Basisregistratie Adressen en Gebouwen", "BagId" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{16}$" } } ], "responses": { "200": { "description": "Address found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "found": true, "address": { "bag_nummeraanduiding_id": "0363200000218908", "bag_verblijfsobject_id": "0363010000218908", "bag_pand_ids": [ "0363100012165277" ], "bag_openbare_ruimte_id": "0363300000006316", "bag_woonplaats_id": "3594", "street": "Damrak", "short_name": "Damrak", "house_number": 1, "house_letter": null, "house_number_addition": null, "postcode": "1012LG", "city": "Amsterdam", "municipality": "Amsterdam", "address_line": "Damrak 1", "address_line_postal": "1012 LG AMSTERDAM", "usage_purposes": [ "retail" ], "surface_area_m2": 312, "build_year": 1900, "status": "in_use", "type": "residence", "is_secondary_address": false, "is_observed": false, "in_investigation": null, "document_date": "2019-11-22", "document_number": "19SZ2048", "secondary_address_ids": [], "occurrence": null, "lat": 52.3745, "lon": 4.8986 } } ], "properties": { "found": { "type": "boolean" }, "address": { "type": "object", "properties": { "bag_nummeraanduiding_id": { "type": "string" }, "bag_verblijfsobject_id": { "type": "string" }, "bag_pand_ids": { "type": "array", "items": { "type": "string" } }, "bag_openbare_ruimte_id": { "type": "string" }, "bag_woonplaats_id": { "type": "string" }, "street": { "type": [ "string", "null" ] }, "short_name": { "type": [ "string", "null" ] }, "house_number": { "type": "integer" }, "house_letter": { "type": [ "string", "null" ] }, "house_number_addition": { "type": [ "string", "null" ] }, "postcode": { "type": "string" }, "city": { "type": "string" }, "municipality": { "type": "string" }, "address_line": { "type": "string" }, "address_line_postal": { "type": "string" }, "usage_purposes": { "type": "array", "items": { "type": "string" } }, "surface_area_m2": { "type": [ "integer", "null" ] }, "build_year": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "is_secondary_address": { "type": "boolean" }, "is_observed": { "type": [ "boolean", "null" ] }, "in_investigation": [], "document_date": { "type": [ "string", "null" ] }, "document_number": { "type": [ "string", "null" ] }, "secondary_address_ids": { "type": "array", "items": { "type": "string" } }, "occurrence": [], "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] } }, "required": [ "bag_nummeraanduiding_id", "bag_verblijfsobject_id", "bag_pand_ids", "bag_openbare_ruimte_id", "bag_woonplaats_id", "street", "short_name", "house_number", "house_letter", "house_number_addition", "postcode", "city", "municipality", "address_line", "address_line_postal", "usage_purposes", "surface_area_m2", "build_year", "status", "type", "is_secondary_address", "is_observed", "in_investigation", "document_date", "document_number", "secondary_address_ids", "occurrence", "lat", "lon" ] } }, "required": [ "found", "address" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "description": "BAG nummeraanduiding ID not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "found": false, "address": null } ], "properties": { "found": { "type": "boolean" }, "address": { "type": "null" } }, "required": [ "found", "address" ] } } } }, "503": { "description": "Upstream source (PDOK) unavailable or timed out (8 s)", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "found": false, "address": null } ], "properties": { "found": { "type": "boolean" }, "address": { "type": "null" } }, "required": [ "found", "address" ] } } } }, "402": { "description": "Payment Required" } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }