API v1 · Stable · JSON over HTTPS

A postcode in, a full read out.

REST endpoint, Bearer token auth, JSON in and out. Every response is cached for 24 hours. Cached hits don't count against your quota.

✓ REST✓ JSON✓ Bearer auth✓ 30 req/min✓ 24h cache✓ HTTPS only
Quickstart

Three steps, under two minutes.

01
Get a key

Subscribe to a Developer, Business, or Growth plan. Generate a key from the dashboard.

02
Send a request

POST a postcode and an intent to /api/v1/report with your Bearer token.

03
Read the report

Back comes a score, five weighted dimensions, a narrative, recommendations, and citations.

bash
curl -X POST https://www.area-iq.co.uk/api/v1/report \
  -H "Authorization: Bearer aiq_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"area": "Shoreditch", "intent": "business"}'
Authentication

Bearer token on every request.

Every request carries an Authorization header with a 48-character hex token prefixed with aiq_. Generate and revoke keys from your dashboard.

http
Authorization: Bearer aiq_your_api_key_here
Security

Keys carry full account access. Do not ship them in client-side code or public repositories. If a key is exposed, revoke it from the dashboard. Revocation is instant.

Endpoint

One endpoint. One verb.

POSThttps://www.area-iq.co.uk/api/v1/report

HTTPS only. Plain HTTP is rejected. Content-Type must be application/json.

Request body

Two fields. That's the contract.

FieldTypeRequiredDescription
areastringYesUK area name or postcode. e.g. "Shoreditch", "SW1A 1AA", "Manchester city centre". Max 100 characters.
intentstringYesOne of: moving · business · investing · research. Determines which five dimensions get computed and how they're weighted.

Intent types + their dimensions

movingMoving homeSafety · Schools · Transport · Amenities · Cost of Living
businessOpening a businessFoot Traffic · Competition · Access · Spending Power · Costs
investingProperty investingPrice Growth · Rental Yield · Regeneration · Demand · Risk
researchResearch profileSafety · Transport · Amenities · Demographics · Environment
Response

A score, five dimensions, and the reasoning.

A successful request returns 200 OK with a report ID and the full report object.

Schema

idstringUnique report ID. Prefixed rpt_.
report.areastringNormalised area name.
report.intentstringIntent type used for scoring.
report.area_typestringurban | suburban | rural. Benchmark category.
report.areaiq_scorenumberOverall weighted score 0–100 (integer).
report.sub_scores[]SubScore[]Exactly five dimensions keyed to the intent.
report.sub_scores[].labelstringDimension name. Varies per intent.
report.sub_scores[].scorenumberDimension score 0–100 (integer).
report.sub_scores[].weightnumberRelative weight. Sums to 100 across all five.
report.sub_scores[].reasoningstringData-backed explanation for this score.
report.summarystring2–3 sentence executive summary.
report.sections[]Section[]4–6 detailed analysis sections.
report.recommendations[]string[]3+ actionable recommendations.
report.property_dataobjectMedian sold price + YoY change + transaction counts.
report.schools_dataobjectSchools within 1.5km with Ofsted ratings (England).
report.data_sources[]string[]Datasets that contributed to this report.
report.data_freshness[]Freshness[]Per-source period + status (live/recent/static).
report.generated_atstringISO 8601 timestamp.

Example response

json
{
  "id": "rpt_1709834567_a1b2c3",
  "report": {
    "area":          "Shoreditch, London",
    "intent":        "business",
    "area_type":     "urban",
    "areaiq_score":  74,
    "sub_scores": [
      {
        "label":     "Foot Traffic & Demand",
        "score":     82,
        "weight":    30,
        "reasoning": "45,000 daily commuters via Liverpool Street station. 23 restaurants within 500m suggests strong baseline footfall."
      },
      { "label": "Competition Density", "score": 68, "weight": 20, "reasoning": "…" },
      { "label": "Transport & Access",  "score": 79, "weight": 15, "reasoning": "…" },
      { "label": "Local Spending Power","score": 71, "weight": 20, "reasoning": "…" },
      { "label": "Commercial Costs",    "score": 62, "weight": 15, "reasoning": "…" }
    ],
    "summary":         "Shoreditch scores 74/100 for business viability …",
    "sections":        [ { "title": "Location & Demographics", "content": "…" } ],
    "recommendations": [ "Consider locations east of Shoreditch High Street …" ],
    "property_data":   { "median_price": 645000, "price_change_pct": 1.8 },
    "schools_data":    { "rating_breakdown": { ... } },
    "data_sources":    [ "postcodes.io", "police.uk", "IMD 2025", "OpenStreetMap",
                         "Environment Agency", "HM Land Registry", "Ofsted" ],
    "data_freshness":  [ { "source": "Police", "period": "12mo", "status": "live" } ],
    "generated_at":    "2026-04-23T12:34:56.789Z"
  }
}
Errors

Clear codes, one error field.

Non-2xx responses return a JSON object with a single error field describing the issue.

200OKReport generated.
400Bad RequestMissing or invalid area / intent field.
401UnauthorizedMissing, invalid, or revoked API key.
403ForbiddenActive API plan required (Developer / Business / Growth).
429Rate Limited30 req/min exceeded. Retry-After header included.
500Server ErrorInternal error. Retry, or contact support.
json
{
  "error": "Missing required field: area (string)"
}
Rate limits

Per key, sliding window.

The API allows 30 requests per minute per key, tracked as a sliding window. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. 429 responses include a Retry-After header.

The embeddable widget has its own ceiling: 60 requests per hour per origin, cache-only, so public embeds on your property listings never consume API quota.

API
30 req / minute
Per key, sliding window
Widget
60 req / hour
Per origin, cache-only
Cache TTL
24 hours
Cache hits don't count against quota
Data sources

Seven datasets. All public.

Every response carries a data_sources array and a data_freshness block so you can audit exactly which dataset contributed to which claim.

Postcodes.io
ONS / Royal Mail
Geocoding, ward, LSOA, constituency, region, country.
Police.uk
Home Office
Street-level crime, 12-month rolling window, category breakdown.
IMD 2025 / WIMD / SIMD
MHCLG via ArcGIS
Deprivation rank + decile. Covers England, Wales, Scotland.
OpenStreetMap
Overpass API
Schools, amenities, transport stops within 0.5–2km.
Environment Agency
Defra
Flood risk zones + active flood warnings.
HM Land Registry
SPARQL endpoint
Sold prices by postcode district, property types, YoY trends.
Ofsted
Dept for Education
School inspections within 1.5km. England today.
Drop-in widget

One script tag. No API key on the client.

The widget renders a score card on any page. It reads from the 24-hour cache only, so embed traffic never hits live compute and your quota stays intact.

Basic usage

html
<!-- Where the widget should render -->
<div
  data-areaiq-postcode="SW1A 1AA"
  data-areaiq-intent="moving"
></div>

<!-- Before </body> -->
<script src="https://www.area-iq.co.uk/widget.js"></script>

Attributes

data-areaiq-postcodeRequiredUK postcode or area name.
data-areaiq-intentOptionalmoving (default) · business · investing · research.
data-areaiq-themeOptionaldark (default) · light.

Multiple widgets on one page

html
<div data-areaiq-postcode="E1 6AN"   data-areaiq-intent="investing"></div>
<div data-areaiq-postcode="SW11 1AA" data-areaiq-intent="moving"></div>
<div data-areaiq-postcode="M1 1AD"   data-areaiq-intent="business"
     data-areaiq-theme="light"></div>

<script src="https://www.area-iq.co.uk/widget.js"></script>
Code examples

Any HTTP client. No SDK required.

The API speaks plain JSON over HTTPS. Use whatever HTTP client your stack prefers. Below: cURL, Node.js, Python, and Go.

curl -X POST https://www.area-iq.co.uk/api/v1/report \
  -H "Authorization: Bearer aiq_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "area":   "Shoreditch",
    "intent": "business"
  }'

Grab a key. Start building.

Developer plan starts at £49/mo for 100 reports. Cached hits and widget embeds are free on top.

See the plansTalk to sales