# PostcodeTools

> PostcodeTools is a Dutch address data API exposing the official BAG (Basisregistratie Adressen en Gebouwen) register. It provides 47 REST endpoints plus 9 MCP tools and 2 MCP resources (58 in total) covering 10.7M+ addresses, postcode areas, streets, cities, municipalities, and provinces across the Netherlands, updated monthly from the Kadaster source.

The API is developer-first with Bearer-token authentication, CORS support, per-key rate limiting, webhooks, and a Model Context Protocol (MCP) server for AI assistant integration. The free tier allows 1,000 requests per month.

**Base API URL:** https://postcodetools.nl/api/v1
**MCP endpoint:** https://postcodetools.nl/mcp
**Authentication:** Bearer token (API key) — create one after signing up.

## Documentation

- [Getting Started](https://postcodetools.nl/docs/getting-started): Create an API key and make your first address lookup in minutes.
- [Authentication](https://postcodetools.nl/docs/authentication): Bearer-token flow, API-key management, IP allowlists, CORS.
- [Endpoints reference](https://postcodetools.nl/docs/endpoints): All 58 endpoints and MCP tools — addresses, postcodes, cities, municipalities, provinces, geocoding, buildings, batch, search.
- [Concepts](https://postcodetools.nl/docs/concepts): Pagination, filtering, field selection, response format negotiation (JSON / GeoJSON / CSV).
- [Error handling](https://postcodetools.nl/docs/errors): HTTP status codes, problem-details response format, rate-limit headers.
- [Webhooks](https://postcodetools.nl/docs/webhooks): Receive notifications on data changes (new import, schema change).
- [MCP integration](https://postcodetools.nl/docs/mcp): Use PostcodeTools directly from Claude, ChatGPT, or any MCP-capable AI client.

## Dataset

- [BAG directory: provinces](https://postcodetools.nl/provincies): 12 Dutch provinces with address statistics.
- [BAG directory: municipalities](https://postcodetools.nl/gemeenten): 342 Dutch municipalities with drill-down.
- [BAG directory: cities](https://postcodetools.nl/woonplaatsen): 2,600+ Dutch cities (woonplaatsen) with street and postcode data.
- [BAG directory: postcode areas](https://postcodetools.nl/postcodes): 4,000+ Dutch PC4 postcode areas.

## Common questions

- **What is the BAG?** Basisregistratie Adressen en Gebouwen — the official Dutch address and building register, maintained by Kadaster. All PostcodeTools data is sourced from BAG and refreshed monthly.
- **Is the API free?** Yes, a free tier with 1,000 requests/month is available. Paid plans start at 10,000 requests.
- **How do I authenticate?** Sign up for a free account at https://postcodetools.nl/register, generate an API key in the dashboard, and send it as `Authorization: Bearer <key>` on each request.
- **What's the rate limit?** Default 60 requests/minute per key, configurable per API key.
- **What response formats are supported?** JSON (default), GeoJSON, and CSV on applicable endpoints.

## Optional

- [Service status](https://postcodetools.nl/status): Real-time API health and uptime.
- [Contact](https://postcodetools.nl/contact): Support and business enquiries.
- [Privacy policy](https://postcodetools.nl/privacy) — GDPR-compliant.
- [Terms of service](https://postcodetools.nl/terms)