# Bagviewer Kadaster — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for Dutch addresses with autocomplete, look up building and residential unit details, and access historical records from the National Address and Building Registry. Find properties by coordinates, retrieve comprehensive building information, and explore how addresses and structures have changed over time.

**Category:** Maps & Geospatial | **Website:** [bagviewer.kadaster.nl/](https://bagviewer.kadaster.nl/) | **Docs:** [parse.bot/marketplace/60cda0fd-e996-45db-8797-c59e5f5856eb/bagviewer-kadaster-nl-api](https://parse.bot/marketplace/60cda0fd-e996-45db-8797-c59e5f5856eb/bagviewer-kadaster-nl-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-bagviewer-kadaster-nl-api-60cda0fd/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### advanced_search

Search for addresses using structured fields (city, street, house number). Returns matching BAG addresses and other location types (streets, postcodes). At minimum woonplaats must be provided; straat and huisnummer narrow results. Uses PDOK Locatieserver suggest with structured query filters.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `huisnummer` | string | No | House number (e.g. '1', '10'). |
| `straat` | string | No | Street name (e.g. 'Dam', 'Kalverstraat'). |
| `woonplaats` | string | Yes | City/Woonplaats name (e.g. 'Amsterdam', 'Rotterdam'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bagviewer-kadaster-nl-api-60cda0fd/advanced_search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"huisnummer":"<string>","straat":"<string>","woonplaats":"<string>"}'
```

### get_object_history

Retrieve the history/lifecycle of a BAG object. Returns all historical versions (voorkomens) showing how the object changed over time, including geometry changes, status transitions, document references, and validity periods (beginGeldigheid/eindGeldigheid).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `object_id` | string | Yes | BAG object identification number (16 digits, leading zeros preserved, e.g. '0363100012168052'). |
| `object_type` | string | Yes | BAG object type. Accepted values: 'panden', 'verblijfsobjecten', 'nummeraanduidingen'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bagviewer-kadaster-nl-api-60cda0fd/get_object_history \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"object_id":"<string>","object_type":"<string>"}'
```

### get_object_summary

Get summary panel data for a BAG addressable object (verblijfsobject) with expanded nested details. Returns the object's status, geometry, surface area, usage purposes, and embedded address and building information. The response is flattened from the verblijfsobject wrapper.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `object_id` | string | Yes | BAG identification number (16 digits, leading zeros preserved, e.g. '0363010003761571'). Obtainable from search_address_autocomplete.docs[*].adresseerbaarobject_id. |
| `object_type` | string | No | BAG object type path segment. Accepted values: 'adresseerbareobjecten', 'panden', 'verblijfsobjecten', 'nummeraanduidingen'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bagviewer-kadaster-nl-api-60cda0fd/get_object_summary \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"object_id":"<string>","object_type":"<string>"}'
```

### get_pand_details

Get detailed building (pand) information by its 16-digit identification number. Returns building status, geometry (GeoJSON Polygon in RD coordinates), original construction year, and document date. The pand wrapper is flattened so fields are at the top level.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pand_id` | string | Yes | Building (pand) identification number (16 digits, leading zeros preserved, e.g. '0363100012168052'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bagviewer-kadaster-nl-api-60cda0fd/get_pand_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pand_id":"<string>"}'
```

### get_verblijfsobject_details

Get residential unit (verblijfsobject) details by its 16-digit identification number. Returns unit status, surface area (m2), usage purposes, geometry, and HAL links to associated addresses and buildings. The verblijfsobject wrapper is flattened so fields are at the top level.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `vbo_id` | string | Yes | Verblijfsobject identification number (16 digits, leading zeros preserved, e.g. '0363010003761571'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bagviewer-kadaster-nl-api-60cda0fd/get_verblijfsobject_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vbo_id":"<string>"}'
```

### lookup_address_by_id

Retrieve full address details by a PDOK locatieserver ID. Returns a single address record with all available fields including street, house number, postcode, city, coordinates, and BAG object references. The id is obtained from search_address_autocomplete results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | PDOK locatieserver address ID (e.g. 'adr-2a8dc1af055da20b8bcdc8e4dbda1eaa'), from search_address_autocomplete.docs[*].id. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bagviewer-kadaster-nl-api-60cda0fd/lookup_address_by_id \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>"}'
```

### search_address_autocomplete

Autocomplete/typeahead search for addresses, cities, and BAG numbers using the PDOK Locatieserver API. Returns up to 10 matching address suggestions from the BAG registry. Query matches against street names, house numbers, postcodes, and city names. Results are ranked by relevance score.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword for address lookup (e.g. 'Dam 1, Amsterdam', 'Kalverstraat 10'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bagviewer-kadaster-nl-api-60cda0fd/search_address_autocomplete \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### search_by_coordinates

Find BAG building (pand) objects near specific geographic coordinates in the Dutch RD (Rijksdriehoeksstelsel) coordinate system. Returns buildings whose geometry contains or is near the given point, including their identification, construction year, status, and full polygon geometry.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `object_type` | string | No | Type of objects to search for. Currently only 'panden' is supported. |
| `x` | string | Yes | RD X coordinate as a numeric string (e.g. '121394'). |
| `y` | string | Yes | RD Y coordinate as a numeric string (e.g. '487383'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bagviewer-kadaster-nl-api-60cda0fd/search_by_coordinates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"object_type":"<string>","x":"<string>","y":"<string>"}'
```