HomAI Developers ← Back to sign in

The HomAI Partner API

Query Norwegian property intelligence — official registry facts, climate-hazard scores, planning & hazard zones, LiDAR terrain, and our roof & insurance assessment — for any address or coordinate. One authenticated GET returns exactly the data sections your key is scoped for.

Authentication Endpoints Parameters Data scopes Rate limits Example Errors Get a key

Authentication

Every request is authenticated with a secret API key sent in the X-API-Key request header. Keys look like homai_ followed by a long hex string, are issued per customer, and carry their own data scopes and rate limit. Treat a key like a password — send it only over HTTPS and never embed it in client-side code.

# every call carries your key in a header
X-API-Key: homai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

Base URL: /test2/index.php?r=api%2Fv1 (on this deployment). All endpoints are read-only GET and return JSON.

GET`/test2/index.php?r=api%2Fv1/property`

The main endpoint. Resolves a location three ways and returns every section your key is scoped for. Provide one of: address, lat+lng, or a stored id.

GET`/test2/index.php?r=api%2Fv1/scopes`

Returns the full list of available scopes and the scopes granted to your key — useful for discovering what your plan includes.

Parameters

Param	Type	Notes
`address`	string	Free-text Norwegian address, e.g. Solheimsgaten 7C, 5054 Bergen. Geocoded via Kartverket.
`lat` + `lng`	number	WGS84 decimal degrees. Use instead of `address`.
`id`	integer	Id of a property already stored in HomAI (returns its saved analysis too).

Data scopes

Your key only returns the sections it was granted. Available scopes:

Scope	Returns
`property_basic`	Address, matrikkel & coordinates
`eiendom`	Building registry (Kartverket)
`climate_hazards`	Climate hazard scores (NVE / NIBIO / MET)
`plan_zoning`	Reguleringsplan / faresone / hensynssone
`terrain`	LiDAR terrain (slope, height, runoff)
`roof_analysis`	Roof risk score + perceived facts
`insurance`	Insurance assessment
`images`	First-party / official imagery references

Rate limits

Each key has a per-minute request limit (set when the key is issued). Exceeding it returns 429 rate_limited with a retry_after_s hint. Every call — successful or not — is metered against your account for billing and quota.

Example

Request

curl -s "https://YOUR-DOMAIN/test2/index.php?r=api%2Fv1/property?address=Solheimsgaten%207C%2C%205054%20Bergen" \
  -H "X-API-Key: homai_xxxxxxxxxxxxxxxxxxxxxxxx"

Response (scoped sections only)

{
  "ok": true,
  "point": { "lat": 60.382, "lng": 5.337 },
  "property": { "address": "Solheimsgaten 7C, 5054 Bergen", "municipality": "Bergen" },
  "climate": { "climate_score": { "value": 4.1, "max": 10 } },
  "plan":    { "zones": [ { "type": "Hensynssone", "name": "Bevaring kulturmiljø" } ] },
  "terrain": { "terrain_slope_deg": 3.4, "building_height_m": 9.1 },
  "roof":    { "risk_score": 38, "risk_level": "Medium" },
  "insurance": { "classification": "Standard" },
  "attribution": "Kartverket/Geonorge (CC BY 4.0), NVE, NIBIO, MET; analysis © HomAI"
}

Errors

Status	error	Meaning
`401`	`invalid_or_missing_api_key`	No / unknown / revoked key.
`400`	`provide id, lat+lng, or address`	No resolvable location given.
`403`	`forbidden_category`	The property is outside your key's allowed categories.
`429`	`rate_limited`	Per-minute limit hit — retry after `retry_after_s`.
`404`	`unknown_endpoint`	Path is not an API v1 endpoint.

Requesting access

API keys are issued by your HomAI administrator with the scopes and rate limit that match your agreement. To request access:

Contact your HomAI account administrator and state the data scopes you need (see the table above) and your expected request volume.
The administrator issues a key from Admin → Partner API keys. The secret is shown once at creation — store it securely.
Send the key in the X-API-Key header on every request.

Licensing

Our analysis & insurance assessment and CC-BY official facts (Kartverket / NVE / NIBIO / MET) may be re-exposed with attribution. Raw third-party imagery (Google / Esri / NIB) is not redistributed — image scopes return first-party / open-source references only.