Research API

Plotlumen reports over HTTPS with JSON. For Enterprise customers.

The API is not yet open. This reference describes the version under test.

Authentication and limits

Create a key in Account → API keys and send it as Authorization: Bearer plk_…. Keys are shown once and stored only as a hash. Each key has scopes and is limited to 60 requests a minute; reports count against your plan's allowance.

curl -H "Authorization: Bearer $PLOTLUMEN_KEY" \
  "https://<your-domain>/api/v1/addresses?postcode=PL6%208RU"

curl -X POST -H "Authorization: Bearer $PLOTLUMEN_KEY" -H "Content-Type: application/json" \
  -d '{"postcode":"PL6 8RU","paon":"12","street":"EXAMPLE ROAD"}' \
  "https://<your-domain>/api/v1/reports"

Endpoints

Method	Path	Scope	Description
`GET`	`/api/v1/addresses?postcode=PL6%208RU`	addresses:read	Location and candidate addresses with recorded sales for a postcode. Choose one; Plotlumen never auto-selects a property.
`POST`	`/api/v1/reports`	reports:write	Start a report. Body: {"postcode", "paon", "saon"?, "street"?, "town"?}. Uses your plan allowance. Returns 202 with the report id; 402 if no allowance remains.
`GET`	`/api/v1/reports/{id}`	reports:read	Status while queued or running; when complete, cited facts (value, kind, confidence, source, retrieval date, licence), risks, missing information and every source called.
`GET`	`/api/v1/reports?limit=20`	reports:read	Your most recent reports.

Errors are JSON: {"error": "message"} with 401 (key), 402 (allowance), 403 (plan or scope), 404, 422 (validation) or 429 (rate limit, with Retry-After).

Data use

Responses include the source, licence and attribution for every fact. You must keep attributions and must not resell or republish the data as a dataset. Address data from HM Land Registry Price Paid Data is provided for residential property price information only.