Guide for AI agents

Short workflow: choose the path that matches the task

Research and reasoning

1. Search the wiki, choose a topic, or open a known source.
2. Read the source description and operation parameters before running a lookup.
3. Follow canonical company, person, place, vessel, dataset or record links to avoid joining records by names alone.
4. Check source, unit, geographic scope, observation time and retrieval time before drawing a conclusion.
5. Distinguish an empty result from an unavailable source. An upstream failure is not evidence that no data exists.

Software, analysis and dashboards

1. Use HTML to choose the correct source and operation.
2. Open the JSON API index, then the source's names-only view.
3. Read the selected operation descriptor for parameters, schema confidence, errors and its JSON GET template.
4. Fetch the JSON operation and read data. Use entities and relationships for stable cross-source links.
5. Display provenance and retrieval time, follow pagination or truncation recovery, and obey cache headers.

The inexpensive discovery ladder

1. /wiki/api/v1/ — orientation and source list.
2. /wiki/api/v1/kilder/weather?view=names — operation names, short descriptions and descriptor links.
3. /wiki/api/v1/kilder/weather/get_forecast/schema — one operation's parameters and contracts.
4. /wiki/api/v1/kilder/weather/get_forecast?lat=60.39&lon=5.32&hours=24 — the data call.

How to read a JSON response

data

The operation's upstream payload. This is normally what a chart, table or calculation consumes.

entities

Normalized identifiers and labels that can connect the result to other sources. Prefer canonical_id, which includes an identifier namespace, when joining records.

relationships

Explicit links such as a job to its employer or a procurement notice to its buyer. Do not infer relationships that are not present.

_meta

Retrieval time, source provenance, cache state, pagination and possible truncation information.

_links

URLs for the same request, source discovery, canonical wiki resources and useful next steps.

Canonical resource means the preferred stable wiki/API page for an identified object. Prefer its identifier over a display name when joining data.

Schema confidence and generated types

Use codegen_safe: true as the gate for typed model generation. The accompanying status explains how precise the model can be:

• declared — independently maintained response contract; suitable for strict generated models.
• inferred — safe for models of the currently published fields; allow additional fields because the contract is derived from implementation.
• incomplete — not codegen-safe for typed models. Known container shapes and field names remain useful, while unresolved values accept arbitrary JSON.

Only declared contracts publish response examples. Inferred and incomplete descriptors deliberately omit synthetic “example value” payloads.

Errors and retries

{
  "error": {
    "code": "SOURCE_UNAVAILABLE",
    "message": "The data source could not provide a response.",
    "retryable": true
  },
  "suggestion": "Retry later or use another source.",
  "_meta": {},
  "_links": {}
}

• Check the HTTP status before reading data.
• Correct 400 requests and identifiers before retrying.
• Treat 404 as no matching entity for that exact lookup, not proof that the real-world object does not exist.
• Retry 429, 502 and 503 only when error.retryable is true, using backoff.

Pagination, truncation and caching

• Use limit and offset; continue with _meta.pagination.next_offset until it is null.
• If _meta.truncated is true, inspect truncated_fields and follow truncation_recovery rather than assuming the response is complete.
• Follow Cache-Control and ETag. Do not poll more frequently than the source TTL.
• The API supports browser CORS, so a client-side dashboard can fetch JSON directly.

Worked example: a Bergen energy dashboard

1. Use the HTML source pages to confirm that Strompris supplies NO5 spot prices and Weather supplies coordinate forecasts.
2. Read the descriptors for strompris/get_prices and weather/get_forecast.
3. Fetch electricity prices for the selected date and weather for the dashboard coordinate.
4. Chart data.prices by hour and show forecast temperature beside it. Join Strompris time_start_utc to Weather time; do not join local clock text or array positions.
5. Show bidding zone, units, source names and _meta.retrieved_at. Surface a partial-data warning if either source fails.

Worked example: company activity dashboard

1. Search for the company and confirm its organization number on the canonical company page.
2. Use Brreg for current official status, Firmafakta for linked company facts, Doffin for procurement and Arbeidsplassen for jobs.
3. Join organization entities using canonical_id, not company names. Keep procurement-buyer and job-employer relationships explicit.
4. Show the reporting period or deadline for every time-sensitive record, and do not describe an expired job or notice as current.
5. Render each source independently so one unavailable source produces a partial-data warning instead of an empty company profile.

Worked example: local conditions dashboard

1. Resolve the address with Geonorge and confirm the canonical place coordinate.
2. Fetch the concise place summary first; request weather, air, transport, charging or maritime sections only when the dashboard needs them.
3. Join coordinate series by timestamp and location. State the radius for nearby stations, vessels, charging points or detections.
4. Label observations and forecasts separately. A nearby result is not necessarily located at the selected address.
5. Follow truncation_recovery if a section is partial and show source-specific availability.

Worked example: statistical comparison

1. Search for the table, then inspect its metadata, dimensions, units and update date.
2. Select explicit values for every dimension and keep the requested extract bounded.
3. Join tables only after checking that geography, population, unit, frequency and period definitions are compatible.
4. Preserve table IDs and dimension codes in the dashboard so the query can be reproduced.
5. Flag revisions, missing periods and definition breaks instead of interpolating them silently.

Common links across sources

• Company → official register data, roles, procurement, jobs and grants.
• Place → weather, air quality, public transport, charging, fire and maritime data.
• Vessel, port or aquaculture site → canonical object → coordinate → place context.
• Statistics → table metadata, dimensions and units → related Statistics Norway, Norges Bank or data.norge.no resources.