Docs

Developer reference for the Locastica API

Start with one postcode lookup, review the response shape, and download the OpenAPI document. The API returns official-source licensing intelligence for England with evidence links, published fee context, freshness, and clear usage limits.

Download OpenAPI Start API workspace

Authentication summary

Use Authorization: Bearer <api_key> by default.

x-api-key is also accepted when your client cannot send an Authorization header.

Self-serve API keys begin with lk_live_ and are created at /account/api-keys.

API access starts on Portfolio. Professional raises the monthly allowance, and Scale raises it again for larger internal teams. Contact us if you need embedded delivery, webhooks, or broader commercial rights.

Getting started

Sign up

Create a Locastica account so the API usage belongs to a real workspace.

Upgrade to Portfolio, Professional, or Scale

API access starts on Portfolio (1,000 requests per month). Professional and Scale raise the allowance for higher internal usage. Contact us if you need embedded delivery or broader commercial rights.

Create a key in /account/api-keys

Issue a key from the account workspace. Keys are created with the `lk_live_` prefix and shown in plaintext once.

Make the first lookup request

Send one postcode lookup with an API key header and inspect the response payload.

Check usage headers

Read the monthly allowance and burst headers on each response so you can monitor usage.

Revoke unused keys

Use the same account workspace to revoke old environment keys instead of reusing one shared secret everywhere.

Plans and usage

Portfolio includes 1,000 requests per month with a 30-per-minute burst for light integrations. Professional raises that to 5,000 requests per month with a 60-per-minute burst, and Scale takes that to 20,000 requests per month with a 120-per-minute burst for larger internal teams.

This reference covers the postcode lookup route and the public reference endpoints listed below. Contact us if you need embedded delivery, webhook access, or additional support beyond the self-serve ladder.

Base URL: https://locastica.com

OpenAPI JSON: /api/openapi.json

Full docs: /docs/api

Evaluate before upgrading

Technical buyers can inspect the response contract before checkout. The sample response below is intentionally complete enough to test field mapping without an API key.

Inspect the response first

Use the sample JSON on this page to confirm the council, scheme, evidence, fee, freshness, and coverage fields before you create a paid workspace.

Create a workspace when the shape fits

Scale only after repeated use is clear

Move from Portfolio to Professional or Scale when monthly volume, burst needs, or team workflow make the higher allowance necessary.

First request

Start with the bearer header. Keep one active key per environment or use case.

curl --request GET \
  "https://locastica.com/api/v1/licensing/lookup?postcode=SE17+1PU" \
  -H "Authorization: Bearer lk_live_your_key" \
  -H "Content-Type: application/json"

Alternative header when `Authorization` is unavailable:

curl --request GET \
  "https://locastica.com/api/v1/licensing/lookup?postcode=SE17+1PU" \
  -H "x-api-key: lk_live_your_key" \
  -H "Content-Type: application/json"

Usage headers

X-Api-Monthly-Limit

Account-wide monthly request allowance for API-enabled plans.

X-Api-Monthly-Used

Requests already used in the current monthly window across active keys.

X-Api-Monthly-Remaining

Requests still available in the current monthly window.

X-Api-Monthly-Reset

ISO timestamp for the next monthly usage reset.

X-Api-Burst-Limit

Per-key burst ceiling in requests per minute.

Endpoint catalogue

Paths are listed here as reference. Use the request examples or the OpenAPI document to call them with the required query parameters and authentication or browser protection headers.

GET

/api/v1/licensing/lookup

Resolve a single postcode into council context, applicable schemes, fee visibility, evidence links, freshness, and coverage.

Auth: API key via `Authorization: Bearer <api_key>` or `x-api-key: <api_key>`. Browser callers can use the public session path instead.

Request shape

Query: `postcode` (required string)

Response shape

`postcode`, `ward`, `council`, `schemes[]`, `coverage`, optional `message`
`schemes[]` include `id`, `type`, `name`, `status`, `lifecycleStatus`, `coverageType`, `fees`, `sourceUrl`, `confidence`, `lastVerified`

GET

/api/v1/stats

Return national council coverage totals and quality percentages.

Auth: Public route with browser protection. This endpoint does not currently use API keys.

Request shape

No query parameters

Response shape

`total`, `withSchemes`, `withFullData`, `withPartialData`, `withMinimalData`
`coverage.full`, `coverage.partial`, `coverage.minimal`

GET

/api/v1/timeline

Return the England-wide obligation timeline with trust metadata and coverage badges.

Auth: Public route with browser protection. Optional session enrichment adds `user_id` when available.

Request shape

Optional query: `category`, `from`, `to`

Response shape

`items[]`, `total`, top-level `coverage_badge`, top-level `trust_metadata`, `user_id`
`items[]` include `id`, `title`, `description`, `date`, `phase`, `status`, `category`, `ruleset_id`, `effective_from`, `trust_metadata`, `coverage_badge`

Response examples

GET /api/v1/licensing/lookup

{
  "postcode": "SE17 1PU",
  "ward": {
    "code": "E05014156",
    "name": "Faraday"
  },
  "council": {
    "code": "E09000028",
    "name": "London Borough of Southwark",
    "region": "London",
    "website": "https://www.southwark.gov.uk",
    "licensingUrl": "https://www.southwark.gov.uk/housing/private-tenants-and-landlords/private-rented-property-licensing/apply-private-rented-1",
    "dataQuality": "FULL",
    "lastVerified": "2026-03-15T00:00:00.000Z"
  },
  "schemes": [
    {
      "id": "scheme_southwark_selective",
      "type": "selective",
      "name": "Selective licensing",
      "status": "active",
      "lifecycleStatus": null,
      "coverageType": "COUNCIL",
      "fees": {
        "newApplicationFee": 945,
        "renewalFee": 750
      },
      "sourceUrl": "https://www.southwark.gov.uk/housing/private-tenants-and-landlords/private-rented-property-licensing/apply-private-rented-1",
      "confidence": 0.92,
      "lastVerified": "2026-03-15T00:00:00.000Z"
    }
  ],
  "coverage": "FULL"
}

GET /api/v1/stats

{
  "total": 317,
  "withSchemes": 275,
  "withFullData": 228,
  "withPartialData": 47,
  "withMinimalData": 42,
  "coverage": {
    "full": 72,
    "partial": 15,
    "minimal": 13
  }
}

GET /api/v1/timeline

{
  "items": [
    {
      "id": "rra-2025-phase1",
      "title": "Renters' Rights Act - Phase 1",
      "description": "Section 21 abolition, new possession grounds, PRS Database initial registration",
      "date": "2026-05-01",
      "phase": "Phase 1",
      "status": "current",
      "category": "prs_database",
      "ruleset_id": "RRA-ENG-2025",
      "effective_from": "2026-05-01",
      "trust_metadata": {
        "sources": [
          "https://www.gov.uk/government/collections/renters-rights-bill"
        ],
        "confidence": "high",
        "vintage": "2026-04-18T00:00:00.000Z"
      },
      "coverage_badge": {
        "geo": {
          "scope": "ENGLAND"
        },
        "ruleset": {
          "id": "RRA-ENG-2025"
        },
        "data": {
          "level": "FULL"
        }
      }
    }
  ],
  "total": 1,
  "coverage_badge": {
    "geo": {
      "scope": "ENGLAND"
    },
    "ruleset": {
      "id": "TIMELINE-2025"
    },
    "data": {
      "level": "FULL"
    }
  },
  "trust_metadata": {
    "sources": [
      "https://www.gov.uk/government/collections/renters-rights-bill"
    ],
    "confidence": "high",
    "vintage": "2026-04-18T00:00:00.000Z"
  },
  "user_id": null
}

Error codes

400 Missing or invalid request input

bad_request

Required query or body input was missing or malformed.

401 Authentication failed

invalid_authorization | invalid_api_key | api_key_revoked

The supplied key was missing, malformed, unknown, or revoked.

403 Plan no longer includes API access

plan_ineligible

The key is valid, but the account no longer has an API-enabled plan.

404 Resource not found

not_found

Reserved for account-backed resources such as missing keys or jobs. The three public read endpoints below do not currently emit 404.

429 Allowance or burst limit reached

monthly_limit_exceeded | rate_limit_exceeded

The account-level monthly allowance or the per-key burst ceiling has been exhausted.

500 Unhandled server error

internal_error

A request reached the service but could not be completed successfully.

Reference notes

The postcode lookup route is the main API-key endpoint. If you want answers across a real batch of properties, start on the portfolio-audit route instead of running large postcode loops during evaluation.

The stats and timeline endpoints are listed here for completeness. They support the wider Locastica experience and do not use the same API-key model as the postcode lookup route.

The machine-readable spec at /api/openapi.json mirrors this page.