# NL AHN Hoogtedata Lookup per Adres (`codeclouds/nl-ahn-hoogtedata-lookup`) Actor

Looks up ground-level (DTM) and surface (DSM) elevation from the official Dutch AHN height map for any address, postcode, or coordinate, plus the derived building/vegetation height above ground.

- **URL**: https://apify.com/codeclouds/nl-ahn-hoogtedata-lookup.md
- **Developed by:** [Dennis](https://apify.com/codeclouds) (community)
- **Categories:** Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 locatie-resultaats

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## NL AHN Hoogtedata Lookup per Adres

Looks up official Dutch elevation data — ground level (DTM) and surface height (DSM, including
buildings and vegetation) — from the national AHN height map for any address, postcode, or
coordinate. Also returns the derived above-ground height (building/vegetation height), computed
from the difference between surface and ground level.

### When should an AI agent use this?

- "What is the ground-level elevation at this address, relative to NAP?"
- "How tall is the building at this address, based on official elevation data?"
- "Check flood-risk-relevant ground elevation for a batch of addresses."
- "Get the surface height (including rooftops) at these coordinates for a solar-panel orientation study."
- "Compare ground elevation across a list of addresses for a drainage/water-management analysis."
- "Estimate building or tree-canopy height above ground for these locations."

### What this Actor does

- Geocodes any Dutch address, postcode, place name, or `"lat,lon"` coordinate via the official PDOK Locatieserver
- Queries the official AHN (Actueel Hoogtebestand Nederland) WCS, PDOK/RWS, for the DTM (ground level) and DSM (surface height) at that location — 0.5m resolution, CC0
- Returns ground level as the **median of the surrounding data** rather than the single exact pixel — because AHN's ground layer has no data directly under a building's roof, sampling only the exact point often returns nothing for addresses (which are usually on top of a building)
- Returns surface height as the exact pixel at the point (e.g. the rooftop height)
- Computes the derived above-ground height (surface minus ground) — a rough proxy for building or vegetation height
- Processes up to 50 locations per run, with configurable concurrency

### Input

| Field | Type | Description | Example |
|---|---|---|---|
| `locaties` | array of strings | Address, postcode, place name, or `"lat,lon"` per location (1-50) | `["Bathseweg 27, Rilland"]` |
| `concurrency` | integer | How many locations to process in parallel | `3` |

### Output

```json
{
  "invoer": "Bathseweg 27, Rilland",
  "gevonden": true,
  "fout": null,
  "foutcode": null,
  "weergavenaam": "Bathseweg 27, 4411BA Rilland",
  "postcode": "4411BA",
  "gemeente": "Reimerswaal",
  "provincie": "Zeeland",
  "lat": 51.41533763,
  "lon": 4.18586885,
  "geocodingScore": 19.1,
  "geocodingBetrouwbaarheid": "hoog",
  "maaiveldhoogteMeter": 1.81,
  "oppervlaktehoogteMeter": 8.23,
  "opstandhoogteMeter": 6.42,
  "dekkingBeschikbaar": true,
  "eenheid": "m t.o.v. NAP",
  "bron": "AHN WCS (service.pdok.nl/rws/ahn/wcs/v1_0) + PDOK Locatieserver (geocoding)"
}
```

`fout` is a human-readable error message (`null` on success). `foutcode` is a machine-readable
classification for agents/automation, one of:

| Code | Retryable? | Meaning |
|---|---|---|
| `null` | — | No error. |
| `GEEN_GEOCODING_MATCH` | No | PDOK Locatieserver found no match for this input — retrying the same input won't help. |
| `UPSTREAM_ERROR` | Yes | Temporary HTTP/connectivity failure at PDOK Locatieserver or the AHN WCS (after built-in retries) — a later run may succeed. |
| `ONBEKENDE_FOUT` | No | Unexpected error that doesn't fit the categories above. |

### Use cases

- Add ground-elevation context to a flood-risk or drainage analysis for a portfolio of addresses
- Estimate building height for a solar-panel feasibility or shadow-impact study
- Enrich a real-estate or land-development dossier with official elevation data
- Batch-check elevation for a set of construction sites before a site-preparation assessment

### Pricing

This Actor uses Apify's Pay-Per-Event (PPE) pricing model.

- **Actor Start:** $0.00005 (Apify default)
- **locatie-resultaat:** $0.006 per location checked

### Legal

Uses only official, open, CC0-licensed government data: the AHN WCS (PDOK/RWS) for elevation, and
the PDOK Locatieserver for geocoding. No personal data is processed. Elevation values are official
survey-grade AHN data (laser altimetry, ≥10 measurements/m²), but the derived above-ground height
is a simple surface-minus-ground calculation, not a validated building-height measurement — treat
it as an indicative figure.

### FAQ

**Q: Why is the ground-level value a median of the surrounding area instead of the exact point?**
A: AHN's ground layer (DTM) has no laser-ground-return data directly under a roof — since most addresses point at a building, sampling only the exact pixel often returns nothing. The median of the surrounding window gives a meaningful "ground level near this address" value instead.

**Q: What does "above-ground height" measure?**
A: The surface height (DSM, exact point — typically the rooftop or treetop) minus the surrounding ground level (DTM median) — a rough proxy for building or vegetation height, not an official measurement.

**Q: What if a location has no AHN data (e.g. open water)?**
A: `dekkingBeschikbaar` is `false` and the relevant height field(s) are `null` — AHN's DTM excludes water, and DSM excludes most water surfaces too.

**Q: Which AHN version is used?**
A: AHN4 (2020-2022 acquisition), the current version served via PDOK's national WCS at 0.5m resolution.

### Related Actors

- **[NL Bodemrisico Check](https://apify.com/codeclouds/nl-bodemrisico-check)** — same geocoding pattern, checks the same address against known soil contamination instead of elevation.
- **[NL Natura2000 Afstandscheck](https://apify.com/codeclouds/nl-natura2000-afstandscheck)** — same geocoding pattern, checks distance to protected nature areas.
- **[Vastgoed XXL](https://apify.com/codeclouds/vastgoed-xxl)** — combines multiple official Dutch geo-data sources into one property dossier; a natural companion enrichment.

***

*Zoekwoorden: AHN hoogtekaart, maaiveldhoogte, hoogtemeting adres, NAP-hoogte, DTM DSM Nederland, hoogtedata opvragen, gebouwhoogte schatten.*

### Keywords

ahn, elevation, hoogtedata, netherlands, pdok, dtm, dsm, ground-level, building-height, geocoding

### Changelog

#### 0.1.0

- Initial release.

# Actor input Schema

## `locaties` (type: `array`):

Een of meer NL-adressen, postcodes, plaatsnamen, of coordinaten ("lat,lon") om de AHN-hoogtedata voor op te zoeken. Bijvoorbeeld: "Bathseweg 27, Rilland", "6811 AA", of "52.09,5.85".

## `concurrency` (type: `integer`):

Hoeveel locaties tegelijk verwerkt worden (geocoding + AHN-lookup per locatie). Bijvoorbeeld: 3.

## Actor input object example

```json
{
  "locaties": [
    "Bathseweg 27, Rilland"
  ],
  "concurrency": 3
}
```

# Actor output Schema

## `results` (type: `string`):

Alle resultaten in het default dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locaties": [
        "Bathseweg 27, Rilland"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("codeclouds/nl-ahn-hoogtedata-lookup").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "locaties": ["Bathseweg 27, Rilland"] }

# Run the Actor and wait for it to finish
run = client.actor("codeclouds/nl-ahn-hoogtedata-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "locaties": [
    "Bathseweg 27, Rilland"
  ]
}' |
apify call codeclouds/nl-ahn-hoogtedata-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,codeclouds/nl-ahn-hoogtedata-lookup"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/pn2Gz95NUTZCaLEGR/builds/OmH9yK90qfCtDzobb/openapi.json