# Nederland Postcode API

> Address validation and lookup API for Dutch addresses. Validate postcodes, retrieve complete address information, and integrate address autocomplete functionality into your website or application.

## About

Nederland Postcode API provides reliable, up-to-date address validation and lookup services for all addresses in the Netherlands. The API contains over 9 million Dutch addresses that are updated daily, ensuring access to the most accurate and current address information available.

The service is designed for easy integration into websites and applications, offering fast response times (~50ms), 99.9% uptime, and scalable infrastructure suitable for production environments. Users can access the API without managing large datasets or hosting infrastructure.

## API Endpoints

**Base URL:** `https://api.nederlandpostcode.nl/`

All endpoints require authentication via Bearer token in the Authorization header:
```
Authorization: Bearer npa_live_xxx
```

### Available Endpoints

1. **GET /v1/address** - Retrieve address data by postcode and house number
   - Parameters: `postcode` (required), `number` (required), `addition` (optional), `attributes[]` (optional)
   - Returns: Array of addresses matching the criteria

2. **GET /v1/coordinates** - Find nearest address by geographic coordinates
   - Parameters: `latitude` (required), `longitude` (required), `limit` (optional, 1-10, default 1)
   - Returns: Array of addresses sorted by distance

3. **GET /v1/energy-label** - Retrieve energy labels for Dutch properties
   - Parameters: `postcode` (required), `number` (required), `addition` (optional)
   - Returns: Current and historical energy labels

4. **GET /quota** - Check current API usage and limits
   - Returns: Used quota and monthly limit

### Example Requests

**Address lookup:**
```
GET https://api.nederlandpostcode.nl/v1/address?postcode=1118BN&number=800&attributes[]=coordinates
```

**Response:**
```json
{
  "data": [
    {
      "postcode": "1118BN",
      "number": 800,
      "addition": null,
      "street": "Schiphol Boulevard",
      "city": "Schiphol",
      "municipality": "Haarlemmermeer",
      "province": "Noord-Holland",
      "country": "Nederland",
      "coordinates": {
        "latitude": 52.30528553688755,
        "longitude": 4.750645160863609
      }
    }
  ]
}
```

**Coordinate lookup:**
```
GET https://api.nederlandpostcode.nl/v1/coordinates?latitude=52.305285&longitude=4.750645&limit=1
```

**Energy label lookup:**
```
GET https://api.nederlandpostcode.nl/v1/energy-label?postcode=1118BN&number=800
```

**Response:**
```json
{
  "data": [
    {
      "postcode": "1118BN",
      "number": 800,
      "addition": null,
      "street": "Schiphol Boulevard",
      "city": "Schiphol",
      "energy_labels": [
        {
          "inspection_date": "02-08-2022",
          "valid_until_date": "02-08-2032",
          "construction_type": "utiliteitsbouw",
          "building_type": null,
          "energy_label": "A+++",
          "max_energy_demand": 98.4,
          "max_fossil_energy_demand": 55.48,
          "min_renewable_share": 55.3
        }
      ]
    }
  ]
}
```

## Authentication

Two types of API tokens are available:

- **Test tokens** (`npa_test_xxx`): Free testing with limited test postcodes (1015CN and 1118BN)
- **Production tokens** (`npa_live_xxx`): Full access to all 9+ million addresses

Create a free account to get your test token (no credit card required).

## Response Format

All endpoints return JSON with a consistent structure:
- `data`: Array containing results (even for single results)
- Empty array `[]` returned for no matches (with 200 OK status)
- Error responses include `message` and optionally `errors` object

## Status Codes

- `200`: Request successful
- `401`: Unauthorized - invalid or missing API token
- `404`: Invalid API endpoint
- `422`: Invalid request - check parameters
- `428`: Missing required headers
- `429`: Rate limit exceeded

## Rate Limiting

- Per-minute rate limit to prevent abuse (default: 60 requests/minute)
- Monthly quota based on subscription plan
- Check current usage with `/quota` endpoint
- 429 status code returned when limits exceeded

## Data Fields

Standard address response includes:
- `postcode`: Dutch postal code (e.g., "1118BN")
- `number`: House number
- `addition`: House number addition (suffix)
- `street`: Street name
- `city`: City name
- `municipality`: Municipality name
- `province`: Province name
- `country`: Always "Nederland"

With the attributes parameter, you can request additional fields:
- `coordinates`: Latitude and longitude (when requested via `attributes[]=coordinates`)
- `district`: Name of the district that the address belongs to (when requested via `attributes[]=district`)
- `function`: Function of the location (when requested via `attributes[]=function`)
- `location_status`: Status of the location (when requested via `attributes[]=location_status`)
- `property_status`: Status of the property (when requested via `attributes[]=property_status`)
- `surface_area`: Surface area of the property (when requested via `attributes[]=surface_area`)
- `construction_year`: Construction year of the property (when requested via `attributes[]=construction_year`)

## Key Features

- **9+ million addresses**: Complete coverage of all current addresses in the Netherlands, automatically updated daily
- **Address validation**: Validate Dutch postcodes and house numbers to ensure accurate address data entry
- **Address autocomplete**: Enable fast, user-friendly address input with autocomplete functionality
- **Geographic coordinates**: Retrieve latitude and longitude coordinates for each address
- **Energy label data**: Included access to Energy Label API for Dutch residential and commercial properties
- **Fast performance**: Average API response time of ~50ms with 99.9% uptime guarantee
- **No infrastructure required**: Cloud-hosted solution eliminates need for managing 30+ GB datasets or local hosting
- **Developer-friendly**: Comprehensive documentation with code examples for quick implementation

## Use Cases

- E-commerce checkout forms
- Customer registration systems
- Delivery and logistics applications
- CRM systems
- Real estate platforms
- Government services
- Any application requiring Dutch address validation

## Plugins & SDKs

Official plugins available for:
- **PHP**: https://github.com/Label84/php-nederland-postcode
- **Laravel**: https://github.com/Label84/laravel-nederland-postcode
- **WooCommerce**: https://www.postcode-checkout.nl/integraties/woocommerce
- **Contact Form 7**: https://www.postcode-checkout.nl/integraties/contact-form-7
- **Magento**: https://www.postcode-checkout.nl/integraties/magento-2

And more integrations such as PrestaShop, CS Cart, OpenCart and Shopware.

## Main Documentation Pages

- **Homepage**: https://nederlandpostcode.nl - Overview and interactive API demo
- **API Documentation**: https://nederlandpostcode.nl/documentatie - Complete API reference and integration guides
- **Pricing**: https://nederlandpostcode.nl/prijzen - Transparent pricing starting at €59.99/year (less than €5/month)
- **Energy Label API**: https://nederlandpostcode.nl/energielabel-api - Retrieve energy labels for Dutch properties
- **District API**: https://nederlandpostcode.nl/wijken-api - Retrieve the district of a Dutch address
- **Databases**: https://nederlandpostcode.nl/databases - Information about data sources and updates
- **Database Download**: https://nederlandpostcode.nl/postcode-database-downloaden - Database download options
- **Plugins**: https://nederlandpostcode.nl/plugins - Integration plugins for popular platforms
- **FAQ**: https://nederlandpostcode.nl/veelgestelde-vragen - Frequently asked questions
- **Blog**: https://nederlandpostcode.nl/blog - Updates and articles
- **Status Page**: https://status.nederlandpostcode.nl/ - Real-time API status and uptime monitoring

- **OpenAPI Specification (YAML)**: https://nederlandpostcode.nl/openapi.yaml — Machine-readable OpenAPI 3.1.0 specification
- **Interactive API Explorer**: https://nederlandpostcode.nl/openapi — Interactive documentation

## Getting Started

1. Create a free account at https://nederlandpostcode.nl/registreren (no credit card required)
2. Get your test token and try the API with test postcodes (1015CN, 1118BN)
3. Review documentation at https://nederlandpostcode.nl/documentatie
4. Implement the API using provided code examples or plugins
5. Choose a pricing plan when ready for production use (from €59.99/year)

## Contact & Support

- Contact page: https://nederlandpostcode.nl/contact
- Privacy policy: https://nederlandpostcode.nl/privacy-beleid
- Terms and conditions: https://nederlandpostcode.nl/algemene-voorwaarden

## Infrastructure

Hosted in the Netherlands by Leaseweb, ensuring low latency for European users and GDPR compliance.

---

*Last updated: April 2026*