API REFERENCE

One address lookup, the whole context.

Resolve a Norwegian address and get back the sections you ask for — each with its source, its geographic level, its age and its caveats. The field reference is generated from the contract. Check /health for the deployed version and /access for your permissions.

The field lists are not the important part. The caveats are: what a value does not mean. Read an empty section together with source status and coverage; it does not establish absence of hazard.

API version: 1.8.0
Sections: 176
Fields: 2,484
Runnable in the demo: 161

Getting started

The public demo answers without a key. Try it first — it is the fastest way to find out whether the data holds up for your purpose.

curl "https://api.approach.no/api/v1/address-demo/search?q=Storgata%201"
curl "https://api.approach.no/api/v1/address-demo/285717643"

The authenticated API uses the same address IDs and takes an API key in the X-API-Key header. Keys are issued per organisation with explicit per-section grants — a package never grants access to a new source.

curl -H "X-API-Key: $APPROACH_API_KEY" \
  "https://api.approach.no/api/v1/addresses/285717643?include=address_details,hazard_zones"

Create an account and get a key — ten free requests with the trial key, then bundles you buy from the account page. Need fitted data? Data from the Cadastre and other restricted sources need a separate agreement and are switched on per account.

Sign-in and API keys

Your account session renews automatically during session checks for up to seven days after sign-in. Then sign in again. Signing out ends that session; resetting your password ends all sessions.

API keys are separate from your sign-in and do not refresh automatically. Create a new key in your account, store it securely, update your integration and verify it works before revoking the old key. The Rotate button revokes the old key immediately. Sign-out and password changes do not revoke API keys. If a key may have leaked, revoke it immediately.

401: check the key and expiry. 403: check access. 402: check quota or subscription. 429: wait as instructed by Retry-After before retrying. A new key does not reset quota.

Company pilot, new data and support

Start with one use case and five priority fields. Agree 20–50 test addresses, data access and a suitable allowance with us before building your prototype. The standard trial has ten requests and does not unlock every catalogue field.

Tell us which fields are missing, how often they need updating and how you intend to use them. New sources and improved coverage are prioritised by need, quality and usage rights; the catalogue describes what is available now.

Keys belong to the person who created them, even when using the company agreement. Before that person leaves or deletes their account, have another administrator create a replacement key, update and test the integration, then revoke the old key.

For an error, include the time, endpoint, HTTP status and Request ID from Usage & logs. Never send API keys or passwords.

From search to your first lookup

Run on your server. Set APPROACH_API_KEY in the environment and send it in the X-API-Key header. Search, and let the user select an address ID before fetching data. Never put keys in browser code or source control.

// Node.js: keep the key on your server, in an environment variable.
const base = 'https://api.approach.no/api/v1/addresses';
const headers = { 'X-API-Key': process.env.APPROACH_API_KEY };
const search = await fetch(base + '/search?q=Storgata%2012', { headers });
if (!search.ok) throw new Error(await search.text());
const { candidates } = await search.json();
console.log(candidates); // Let your user choose; do not silently pick a home.
// After selection, set ADDRESS_ID to that candidate's address_id.
if (process.env.ADDRESS_ID) {
  const response = await fetch(base + '/' + process.env.ADDRESS_ID + '/sections/address_details', { headers });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
} // Inspect status, freshness and source.

Run a call from here

No key and no account. The response below is what the API returned just now — not a sample that was correct once. Every section has the same button on its own page.

Endpoints

Authenticated

https://api.approach.no/api/v1/addresses

GET/catalogno key required

List every section and its field contract. The catalogue is the contract. It returns each section's fields, source, geographic scope, maximum useful age and caveats, and it is what this reference is generated from. Read it at runtime rather than pinning a field list.

GET/openapi.jsonno key required

OpenAPI 3.1 document for the whole API. Every section has a generated record schema, so a client generated from this document knows the shape of each section's records rather than treating them as opaque objects.

POST/resolve

Resolve an address and return its sections. Takes either an address_id or an exact street, number, letter and postcode — never a free-text search. An address that matches more than one record returns 409 with the candidates rather than picking one.

{"street_name":"Storgata","house_number":1,"postal_code":"0155","include":["address_details","hazard_zones"]}

GET/search

Find candidate addresses by text. Prefix and exact matching over street name, number, letter and postcode, with a typo-tolerant fallback when no prefix match is found and the query is eligible. Optional postal_code, municipality_code or municipality filters narrow the candidates. Returns identities only — never section records.

?q=Storgata%201&postal_code=0155

GET/{address_id}

Get one address with all or selected sections. include selects sections; package selects a curated preset. The two cannot be combined. Sections are fetched in parallel and each carries its own status, so a partial response is normal and partial=true says so.

?include=address_details,hazard_zones,ground_conditions

GET/{address_id}/sections/{section}

Get one section, with pagination. Pass the next_cursor from the previous response; a cursor is bound to its address and section and is rejected anywhere else.

?limit=25

GET/{address_id}/history

Export permitted area time series. Requires the history endpoint permission and grants for the corresponding profile sections. Returns only permitted series as JSON or CSV. from/to accept YYYY or YYYY-MM; absent periods are not zero and current periods may be provisional. One successful history request uses one lookup allowance, regardless of returned rows.

?from=2024&to=2025&format=json

GET/{address_id}/properties

Cadastral property context for an address. Registered property units connected to the address. Paginate address candidates with limit and cursor. A property cursor is bound to its property; source-checked cursors also require matrikkelenhet_id.

?limit=10

GET/properties

Find addresses by cadastral property. Use municipality_code, gnr and bnr. Optional fnr, snr and matrikkelenhet_id require checked source identity. Paginate with limit and the property-bound cursor; unknown identifiers are never inferred.

?municipality_code=0301&gnr=1&bnr=2&limit=10

GET/access

Inspect your own permissions and grant expiry. Answers for the calling credential only. There is no caller-supplied customer or key identifier, so one customer cannot ask about another.

GET/usage

Inspect your own recorded usage over 30 days. Same scoping as /access.

GET/healthno key required

Liveness and deployed version. Reports the running release so a client can tell which contract version answered.

Public demo

https://api.approach.no/api/v1/address-demo

GET/search

Search addresses without credentials. The public demo. Same matching semantics as the authenticated search with a smaller fixed cap, and it returns address identities only.

?q=Storgata

GET/{address_id}

Read the demo projection for one address. Returns only the fields listed in the reviewed publication policy, for the sections that carry them. Restricted licensed and personal data is excluded. An absent section may reflect publication policy, access restrictions or missing source coverage; the catalogue does not guarantee populated records for a particular address. Inspect section status and caveats.

GET/catalog

List what the demo publishes. The demo's own catalogue, marking which sections an anonymous caller can read values from and which are listed but restricted.

Reading a response

Each section answers for itself. A failing section does not take the rest with it, and the response-level partial says at least one could not be read. The two fields you must branch on are status and freshness.

status

Value	Meaning
available	The source answered and there is at least one record on this page.
not_found	The source was queried and returned no records for this address. For spatial layers this only describes the locally loaded dataset and its coverage, not every mapped area or an absence of hazard. Sections that map areas (the district, concession or service area an address lies in) also carry reason, from not_found_reasons, saying what the absence means; they never substitute the nearest area.
restricted	The calling credential has no grant for this section. No records are returned and none were read.
unavailable	The section could not be read. error says why: source_not_loaded means the table has not been collected yet, source_empty means it was collected and holds no rows anywhere (a warning feed with no active warning is empty, not broken), source_read_access_missing means the API role cannot read it, source_timeout means the query did not finish, source_schema_outdated means a collector has not yet upgraded the table. None of these say anything about the address.

freshness

Value	Meaning
cached	The records carry a source timestamp within the section's maximum age.
live	Retrieved directly from the source for this lookup. This describes retrieval, not the age or completeness of the source records.
stale	The records carry a source timestamp older than the section's maximum age. They are still returned; deciding whether that matters is yours.
unverified	The records carry no source timestamp, so their age is unknown. Not a claim that they are current.

Pagination

Both section and property endpoints paginate. Send next_cursor as cursor with the same filters. Section cursors bind to an address and section; property cursors bind to a property. Source-checked property pagination also requires matrikkelenhet_id.

Errors

Code	Meaning
400	Invalid input, unknown section, or a cursor that does not belong to this address and section.
401	No credential, or one that could not be verified.
402	The account request allowance is exhausted. Review the allowance or top up in your account; retrying immediately does not restore it.
403	Authenticated, but without an active address grant — or a section this credential is not granted.
404	No address matches.
409	The address matched more than one record. The candidates are returned; choose one and resolve by address_id.
429	Rate limit exceeded. Retry-After gives the wait in seconds.
503	The address register itself could not be read. Distinct from a section being unavailable.

Packages

A package is a curated preset of sections, not an entitlement. Per-section grants still apply after the preset is expanded.

home_profile4 sections

Home profile. Address identity and cached housing facts. Building coverage and recipient permission must be checked; a package does not establish source completeness or grant rights.

prevention_context10 sections

Prevention context. Observations, forecasts, active hazard warnings, fire-service callout statistics, known emergency-service premises and municipal crime context. Car travel is not response time; area statistics are not a household risk score.

area_context8 sections

Area context. Optional municipal statistics and nearby traffic sensors. This is area context, not household characteristics or a live congestion service.

hazard_screen17 sections

Hazard screen. Mapped natural-hazard zones, events and screening scores around the address. Mapped means prioritised areas only; an empty section is unmapped, not safe, and nothing here replaces a site assessment.

environment_nuisance12 sections

Environment and nuisance. Noise, grid and pollution context from strategic mapping and registers; zone membership and proximity, not measurements at the façade.

neighbourhood_life15 sections

Neighbourhood life. Everyday destinations by straight-line distance from open registers and OpenStreetMap; presence and position are as published, and OSM content is ODbL.

outdoor_recreation12 sections

Outdoor recreation. Trails, recreation areas, nature protection and modelled sun and view around the address.

planning_restrictions15 sections

Planning restrictions. Plans, heritage protection, servitude-like constraints and change signals around the address. Constraints are indications to verify with the authority, never a legal opinion.

civil_protection11 sections

Civil protection. Emergency-service premises, shelters and dispatch geography. Straight-line proximity is not response time.

local_economy9 sections

Local economy. Registered companies at the address, on the same property and within 500 metres, plus aggregate business, insolvency and civic context for the wider area; nothing about an occupant. Sole traders are counted, never named.

All sections (176)

Each section has its own page with fields, types, source, coverage and caveats — and a live try-it for the ones the demo publishes.

Search sections or sourcesOnly sections with public previews

Showing 24 of 176 sections