Parameters, bounds and responses are read from the OpenAPI document the API serves, and the error codes from the same table the API uses. Parameter descriptions are in English, as in the contract.
Contents
With a key
https://api.approach.no/api/v1/addresses
GET
/catalog
no 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.
Takes no parameters.
Responses and error codes
HTTP
Meaning
Codes in the body
200
Section catalog (each section with its category, kind, sensitivity and time shape), the categories in display order, packages and the defaults an unqualified request gets.
List the models Datakilde computes itself. Every model is an ordinary section with a model block in its descriptor: the question it answers, the kind of method, its inputs, what it is validated against and its headline fields. Read one with ?include=<id>, or all of them for an address with ?package=models. Each record carries method, method_version, inputs and validation, and the first caveat says what the estimate is not.
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.
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.
Curated include preset from /catalog; cannot be combined with include. Section grants still apply. With neither include nor package the default package (core, see /catalog defaults) is returned; package=all returns every section.
meta query
string
full | compact default compact
compact (default) serializes source as {id, version, access, max_age_hours, max_age_days} and quality without present_by_field and value_fields: the descriptor is the /catalog entry for that id and version. full repeats each section's complete source descriptor and per-field quality.
limit query
integer
1–100 default 100
—
address_id body
string
^[0-9]{1,18}$
—
house_number body
integer
1–99999
—
include body
array<string>
—
—
letter body
string
—
—
postal_code body
string
^[0-9]{4}$
—
street_name body
string
1–255 characters
—
Responses and error codes
HTTP
Meaning
Codes in the body
200
Resolved address; inspect partial, failed_sections and each section status. A request with neither include nor package returns every section and says so in X-Sections-Hint.
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. When the street exists but the house number does not, the nearest existing numbers come back marked as such (match_mode nearest_number). A place named in q (Storgata 12 Tromsø, Rådhusgata Stavanger) restricts the candidates to it, and place.status says when the street is not there. Optional postal_code, municipality_code or municipality filters narrow the candidates. Returns identities only — never section records.
Parameters
Name
Type
Bounds and default
Description
q query
string
2–160 characters
At least 2 characters. Street prefix, optional house number/letter and place or postcode (Storgata 12 Oslo; Storgata 12A, Bergen; Storgata 12 A, 0155), a 2–4 digit postcode prefix, or postal-area/municipality name prefix. A place after the house number, or a whole place name ending a street query without one (Rådhusgata Stavanger), is matched against postal area and municipality name, ignoring case and æ/ø/å (Tromso finds TROMSØ), and restricts the candidates to that place; the response's place says whether the street is there. When the typed street exists but its house number does not, match_mode=nearest_number returns the nearest existing numbers. When an informative street prefix has no result, match_mode=closest returns typo-tolerant street suggestions. Omit q when supplying a geographic filter. A search without a house letter includes all letters; exact /resolve retains its stricter meaning.
postal_code query
string
^[0-9]{4}$
Exact four-digit postcode filter
municipality_code query
string
^[0-9]{4}$
Exact four-digit municipality code; cannot combine with municipality
municipality query
string
2–100 characters
Municipality name prefix, at least 2 characters; cannot combine with municipality_code
limit query
integer
1–20 default 10
Maximum candidate count; has_more indicates that the query should be narrowed
cursor query
string
—
Opaque next_cursor from the previous page of the same query; paging is limited to the first 1000 results
Responses and error codes
HTTP
Meaning
Codes in the body
200
Explicit candidates only. Empty candidates are a valid no-match result; never automatically choose the first record.
—
400
Invalid, repeated, conflicting or unknown query parameter
Active address access required; cadastral discovery needs address_details, source identities additionally buildings, and dwelling choices additionally dwelling_units. Full property filters without buildings grant are rejected.
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.
Curated include preset from /catalog; cannot be combined with include. Section grants still apply. With neither include nor package the default package (core, see /catalog defaults) is returned; package=all returns every section.
meta query
string
full | compact default compact
compact (default) serializes source as {id, version, access, max_age_hours, max_age_days} and quality without present_by_field and value_fields: the descriptor is the /catalog entry for that id and version. full repeats each section's complete source descriptor and per-field quality.
limit query
integer
1–100 default 100
—
Responses and error codes
HTTP
Meaning
Codes in the body
200
Resolved address; inspect partial, failed_sections and each section status. A request with neither include nor package returns every section and says so in X-Sections-Hint.
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.
compact (default) serializes source as {id, version, access, max_age_hours, max_age_days} and quality without present_by_field and value_fields: the descriptor is the /catalog entry for that id and version. full repeats each section's complete source descriptor and per-field quality.
limit query
integer
1–100 default 100
—
Responses and error codes
HTTP
Meaning
Codes in the body
200
Resolved address; inspect partial, failed_sections and each section status. A request with neither include nor package returns every section and says so in X-Sections-Hint.
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.
Parameters
Name
Type
Bounds and default
Description
address_id path · required
string
^[0-9]+$
—
from query
string
^\d{4}(-(0[1-9]|1[0-2]))?$
—
to query
string
^\d{4}(-(0[1-9]|1[0-2]))?$
—
format query
string
json | csv default json
—
Responses and error codes
HTTP
Meaning
Codes in the body
200
Permitted series only, with original period and geographic grain
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.
Parameters
Name
Type
Bounds and default
Description
address_id path · required
string
^[0-9]{1,18}$
—
limit query
integer
1–100 default 10
Address candidates per property per page
cursor query
string
—
Opaque next_cursor bound to the property. Source-checked pagination also requires matrikkelenhet_id; fallback cursors bind kommune/gnr/bnr.
fnr query
string
^[0-9]{1,8}$
Optional exact feste number from a checked Matrikkel snapshot. Omitted means all choices, 0 means explicit zero; unknown never matches zero. Returns 422 if no authorized checked identity is available.
snr query
string
^[0-9]{1,8}$
Optional exact section number from a checked snapshot. Omitted means all choices, 0 means explicit zero. Returns 422 if no authorized checked identity is available.
matrikkelenhet_id query
string
^[0-9]{1,18}$
Select one official property ID; required with a source-checked next_cursor
Responses and error codes
HTTP
Meaning
Codes in the body
200
Explicit candidates only. Empty candidates are a valid no-match result; never automatically choose the first record.
—
400
Invalid, repeated, conflicting or unknown query parameter
Active address access required; cadastral discovery needs address_details, source identities additionally buildings, and dwelling choices additionally dwelling_units. Full property filters without buildings grant are rejected.
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.
Parameters
Name
Type
Bounds and default
Description
municipality_code query · required
string
^[0-9]{4}$
Municipality code or positive registered gnr/bnr. Leading zeroes on gnr/bnr are normalized.
gnr query · required
string
^[0-9]{1,8}$
Municipality code or positive registered gnr/bnr. Leading zeroes on gnr/bnr are normalized.
bnr query · required
string
^[0-9]{1,8}$
Municipality code or positive registered gnr/bnr. Leading zeroes on gnr/bnr are normalized.
limit query
integer
1–100 default 10
Address candidates per property per page
cursor query
string
—
Opaque next_cursor bound to the property. Source-checked pagination also requires matrikkelenhet_id; fallback cursors bind kommune/gnr/bnr.
fnr query
string
^[0-9]{1,8}$
Optional exact feste number from a checked Matrikkel snapshot. Omitted means all choices, 0 means explicit zero; unknown never matches zero. Returns 422 if no authorized checked identity is available.
snr query
string
^[0-9]{1,8}$
Optional exact section number from a checked snapshot. Omitted means all choices, 0 means explicit zero. Returns 422 if no authorized checked identity is available.
matrikkelenhet_id query
string
^[0-9]{1,18}$
Select one official property ID; required with a source-checked next_cursor
Responses and error codes
HTTP
Meaning
Codes in the body
200
Explicit candidates only. Empty candidates are a valid no-match result; never automatically choose the first record.
—
400
Invalid, repeated, conflicting or unknown query parameter
Active address access required; cadastral discovery needs address_details, source identities additionally buildings, and dwelling choices additionally dwelling_units. Full property filters without buildings grant are rejected.
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.
Takes no parameters.
Responses and error codes
HTTP
Meaning
Codes in the body
200
Current authenticated customer only; no caller-supplied customer or key identifier.
No key and no account, with a lower fixed cap and only the fields in the reviewed publication policy. https://api.approach.no/api/v1/address-demo
GET
/search
no key required
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.
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.
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.
These headers can be read by the client, including from a browser on an allowed origin. The list is the one the API names in Access-Control-Expose-Headers.
Header
Carries
X-RateLimit-Limit
Request cap for the window named by X-RateLimit-Window. A customer can have additional hour, day, week or month caps.
X-RateLimit-Remaining
Requests left in the window named by X-RateLimit-Window; zero when that window refused the call.
X-RateLimit-Reset
When the named request window resets, as Unix seconds.
X-RateLimit-Window
The binding request window: minute, hour, day, week or month. Calendar windows use Europe/Oslo; the repeated autumn hour has separate buckets.
Retry-After
On a 429 or a temporary 503: seconds to wait before retrying.
X-Request-Billing
How this request is billed, e.g. allowance_trial, allowance_prepaid, subscription_postpaid, not_billed_test for an exempt self-service test lookup, not_billed_free on a search, resolve, properties, /access or /usage call (never counted), or not_billed_partial_failure when the lookup is not counted. Set on metered responses and on free routes.
X-Request-Budget
The cap in force: production bundle for trial and prepaid accounts, the monthly safety cap for agreed plans. Absent when the account has no cap or a self-service test key does not spend the production bundle.
X-Request-Budget-Used
Lookups counted this calendar month (Oslo) on agreed plans.
X-Request-Budget-Remaining
What is left under X-Request-Budget. Negative while a paid account uses its grace requests.
X-Request-Balance-Ore
The prepaid balance, in øre, that pays for requests beyond a bundle.
X-Request-ID
The id of this request, always assigned by us. It is the id the usage log on the account page shows. Quote it when reporting a problem.
X-Client-Request-ID
Your own X-Request-ID, echoed back when it is printable ASCII without spaces and at most 128 characters, so the call can be matched in your logs.
ETag
On a catalogue, contract (openapi.json), coverage or dataset-catalogue response: a validator. Send it back as If-None-Match and the API answers 304 Not Modified while nothing has changed.
X-Sections-Hint
On a profile that chose no sections, or asked for package=all: which package applied (the default is core) and how to narrow or widen it with include or package. Absent when include or a package other than all was given.
Content-Disposition
On a download (a data-product result, a job result, a series CSV or an address history CSV): the suggested file name.
X-Data-Product
On a data-product result: the product and version that produced it, as id@version.
X-Data-Licence
On a data-product result: the licence the data is served under.
X-Series-Licence
On a series response: the id of the licence the series is published under. Link points at its text.
X-Data-Points
On a series response: how many observations it holds.
X-Billable-Units
On a series response: the units charged for it, one per started thousand observations and at least one.
Link
On a series response: the licence text, as rel="license". On a deprecated section or dataset: the changelog entry as rel="deprecation" (and rel="sunset" once a date is set), and the replacement as rel="successor-version" where there is one.
Deprecation
On a deprecated section or dataset (RFC 9745): when it was deprecated, as @ followed by Unix seconds. It still answers; plan the move to the successor.
Sunset
On a deprecated section or dataset with a retirement date (RFC 8594): the HTTP date after which it stops answering. Absent while no date is set.
X-Dataset-Schema-Version
On a dataset snapshot download: the schema version of the file, so a warehouse can detect a change before it loads it.
X-Dataset-Refresh-Id
On a dataset snapshot download: the refresh the file was written after. Compare it with the refresh a /records or /changes call reports.
X-Content-SHA256
On a dataset snapshot download: the SHA-256 of the file, to verify the transfer.
X-Test-Customer
true when the key or session belongs to a test customer: one Approach made to try a customer's access without touching it. A test customer's calls are never billed or counted. Absent otherwise.
Packages
A package is a curated preset of sections for the package parameter, not an entitlement. Per-section grants still apply after the preset is expanded.
core6 sections
Core. The small default-sized profile: identity, buildings and dwelling units with their source status, mapped hazard zones and the zoning plan. Fast and cheap to read; pick further packages or include ids for more. A package does not establish source completeness or grant rights.
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_screen19 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_nuisance13 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_restrictions16 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.
models26 sections
Datakilde models. Every estimate Datakilde computes itself, such as noise by source (road, rail, air), settlement under the building, storm-surge freeboard, snow load, solar potential and fire-service response time. Each record carries method, method_version, inputs and validation; an estimate is never the official figure it approximates. Same grants and lookup count as any section.