# Bagviewer Kadaster — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/bagviewer-kadaster/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/bagviewer-kadaster/advanced-search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/bagviewer-kadaster/get-object-history \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/bagviewer-kadaster/get-object-summary \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/bagviewer-kadaster/get-pand-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/bagviewer-kadaster/get-verblijfsobject-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/bagviewer-kadaster/lookup-address-by-id \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/bagviewer-kadaster/search-address-autocomplete \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/bagviewer-kadaster/search-by-coordinates \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"object_type":"<string>","x":"<string>","y":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.