Help
Documentation lives at /docs. Methodology lives at /methodology. Below is the FAQ that covers the common product, API, billing, and account questions.
01 · Getting started
What OneGoodArea is, what the free Developer Sandbox includes, and how to start.
OneGoodArea is the intelligence layer for place. One API serves four products on the same record of every place in Great Britain: Signals (sourced, dated facts), Scores (an explained score for a purpose), Monitor (change on the places you track) and Intelligence (rank, compare, similar places and plain-English questions). Every response carries the methodology version that produced it.
No. The Developer Sandbox is free with no card required, for evaluating the API and exploring the MCP server. It is not licensed for production use. When you are ready for production, book a demo and we run a pilot on one real workflow, moving to an annual contract if it works.
On the free Developer Sandbox, generate an evaluation key, then curl POST https://api.onegoodarea.com/v1/score with body { "area": "M1 1AE", "preset": "moving" } and Authorization: Bearer <your_key>. Full code samples in cURL, Node, Python, and Go live at /docs/api-reference.
Signals returns individual measured values per area (one signal at a time). Scores composes multiple signals into a 0-100 number per a named profile. Monitor watches a portfolio of areas for material change over time and fires signed webhooks. Intelligence accepts a natural-language question, emits a typed plan, and executes it against the time-series store. Same engine underneath, different shapes on top.
The full methodology is public at /methodology. It documents the data sources, the country-scoped percentile design, the scoring formula, the confidence rubric, and the engine version registry. Every response also carries an engine_version stamp so you can cite the exact methodology version that produced any number.
02 · Signals
Deterministic per-area measurements. The atomic unit underneath every product.
A Signal is a single measured value for an area, with explicit source, period (the calendar dates the value describes), confidence (0-1), confidence_reason, normalized_value (0-100), and country-scoped percentile. Examples: deprivation (IMD), violent crime rate, education rating, residential price median, residential price YoY.
65 signals. Deprivation (England IMD 2025, Wales WIMD 2019, Scotland SIMD 2020), crime (police.uk recorded crime by category, total and rate per 1,000 residents; council-area context from Police Scotland and the Home Office where street-level data is not published), schools (Ofsted grades within 1.5km and within 1km; Estyn and Education Scotland no longer publish comparable grades), residential prices (the ONS median and its change over the year for each neighbourhood group, with HM Land Registry sales), amenities (OpenStreetMap), transport (NaPTAN), flood (the Environment Agency, SEPA and Natural Resources Wales), population (Census 2021), and derived signals such as crime trends and comparisons with similar areas. Northern Ireland is not covered.
Every Signal response carries fetch_mode so you know how the value was served. "store" returns from our monthly time-series store (warm path, fast). "live" goes to the source API at request time (cold path, used when the store is unavailable or stale). "hybrid" means part of the dimensions came from the store and part from live. The fetch_mode is honest, not a marketing label.
Confidence is a 0-1 number that reflects how much we trust the value, with a plain-language confidence_reason. Today it is an availability and sample rubric (high if the source is fresh and the sample is wide; medium if data is older or thinner; low if a fallback was used). Statistical confidence intervals are on the roadmap as Phase 7.
03 · Scores
Composing signals into 0-100 numbers per a named scoring profile.
Scores returns a 0-100 number for an area against a named scoring profile, broken down by seven dimensions (Crime, Deprivation, Property, Schools, Amenities, Transport, Environment). Each response shows the dimension values, the weight applied to each, the per-dimension confidence, a sentence of reasoning per dimension, the preset used, the weights_source, and the engine_version that produced it.
Four presets ship today, and the slug is the API parameter: moving (how liveable an area is for a household), business (where to open), investing (what an area looks like as an asset) and research (a balanced read). Transport, schools and amenities rank among neighbourhoods of the same kind, urban, suburban or rural, or against your own cohort.
Yes, two ways. Inline: pass a weights object in the request body and the engine applies it directly. Persisted: create a scoring preset for your organisation (POST /v1/orgs/:id/presets) and pass preset_id later. The Levers admin surface for managing presets is on the roadmap; the API endpoints exist today.
Each dimension reads its own signals. Crime comes from police.uk recorded crime: the rate over twelve months and the share that is violent, with the confidence following the sample. Property reads the ONS median and the sales behind it, deprivation the national index, schools the Ofsted grades in range, amenities and transport the counts nearby, environment the flood exposure. The composition is the same across the four presets; only the weights differ. See /methodology under Scoring.
Because the engine sets the number, not the AI. The same inputs on the same methodology version always give the same score. A golden test fixes the engine's output, every response carries the version that produced it, and every release is published in the changelog with what it changed.
04 · Monitor
Continuous change detection over a portfolio of areas, with signed webhook delivery.
Monitor watches a portfolio of areas for material changes in their signals. Every change says why it moved: the source data, or a OneGoodArea methodology release, named by version. The change report (GET or POST /v1/portfolios/:id/changes; POST also sends signal.changed) and the change feed (GET /v1/portfolios/:id/feed, sent as portfolio.feed after every data refresh) both carry the cause. Webhooks send source-data changes unless your subscription asks for methodology moves too.
POST /v1/portfolios with a name and the areas to track: postcodes, official codes or place ids. Returns a portfolio_id. POST /v1/portfolios/:id/areas adds up to 100 more per call; POST /v1/places/map resolves up to 1,000 records in one call, or 20,000 as a job. GET /v1/portfolios/:id/changes lists the material change rows since a given period.
When you call it, the change report compares each signal's latest period with a baseline (default: the period before it) and keeps a change when the value moved by threshold_pct (default 5%) or more; a price move also needs min_transactions sales in both periods (default 8). The change feed records what each data refresh changed and is sent after the refresh. Every change carries cause: source, method or source_and_method, with the releases behind it.
HMAC-SHA256. The signing secret is returned once when the subscription is created, never on later reads. Each delivery carries X-OneGoodArea-Signature: t=<unix seconds>,v1=<hex>, plus X-OneGoodArea-Event and X-OneGoodArea-Delivery. Recompute HMAC-SHA256 of t.body with your secret and compare in constant time before trusting the payload. Webhook URLs must be public HTTPS. Localhost, private, link-local and unique-local addresses are rejected when the subscription is saved and again at delivery, on the address the hostname resolves to. Redirects are not followed: point the webhook at its final URL.
Each delivery waits 5 seconds. A non-2xx answer or a timeout marks it failed; it is retried twice more within about 30 minutes, with the same delivery id, and marked exhausted after the last one. Return 2xx quickly, and alert on failures at your endpoint. The change report and the feed still list every change.
Any signal with history: crime counts, house prices and sales, schools, amenities and transport counts, deprivation. A new deprivation edition, or any change made by a methodology release, is listed as a methodology change and not sent by webhook unless you ask.
05 · Intelligence
Rank, compare and find similar places, or ask in plain English, over the same stored data. Not a chatbot.
Intelligence accepts a natural-language question, emits a Zod-strict typed plan first, then executes the plan deterministically against the time-series store. The plan is JSON. Every response echoes the executed plan plus plan_source ("nl" or "client") so you can replay any query as a programmatic call without an AI round-trip. AI never sets the numbers; the database does.
Seven today. rank_areas (multi-signal compound filter and sort), get_area (single area lookup), compare_areas (side-by-side comparison), score_area (Scores via the planner), find_peers (k-NN similarity over an LSOA), find_insights (peer-relative anomaly detection), and find_forecast (time-series projection). Each maps to a /v1/<op> endpoint that you can also call directly without natural language.
88.2% on the 17-case curated corpus at the September 2026 run, measured against a specific AI model. The corpus is small by design and version-controlled, so the interval around that number is wide. The harness measures the seam, not the model; the figure is model-specific and re-runs on any model swap. A rejected plan gets one corrected attempt with the reason, and every plan is checked before it runs.
Yes. Save the plan JSON returned in the response. POST /v1/query with the plan in the body and the planner is skipped entirely. Same plan against the same data state returns the same rows. This is the audit-replayable path for compliance and procurement workflows.
No. England, Wales and Scotland are covered, each on its own official geography and deprivation index. Northern Ireland is not covered; an NI postcode returns an empty value rather than a cross-border estimate.
06 · Methodology and data
How numbers are computed, where data comes from, and how you can defend them.
police.uk (street-level recorded crime), the Home Office and Police Scotland (council-area crime where street-level data is not published), the ONS (the National Statistics Postcode Lookup spine, house prices by neighbourhood group, Census 2021 population), the three national deprivation indices (IMD 2025, WIMD 2019, SIMD 2020), HM Land Registry (sales), Ofsted (England school inspections), NaPTAN (transport), OpenStreetMap (amenities), and the Environment Agency, SEPA and Natural Resources Wales (flood). Full source registry on /methodology.
Because England's IMD, Wales's WIMD, and Scotland's SIMD are different methodologies with different domains, weights, and release schedules. A cross-border percentile would be a claim that could not survive a compliance review. We compare England against England, Scotland against Scotland, Wales against Wales by design.
No. The API always runs the current methodology and reports that version on every response. We do not execute or store an organisation-level pin. Each release is published in the changelog with the figures it moved, and Monitor labels a change caused by a release as a method change rather than a move in the area, so a back-test can tell the two apart.
Every product response body carries engine_version, the methodology version that actually ran. Product endpoints also return the same value in X-Engine-Version. There is no version override: the body and header describe the current engine used for that response.
Confidence today is an availability and sample rubric (0-1), with a plain-language confidence_reason. HIGH when the source is fresh and the sample is wide. MEDIUM capped on property-backed dimensions when YoY variance is wide. LOW when a fallback was used or the sample is thin. Calibrated outcome-based statistical confidence intervals are on the roadmap as Phase 7.
v1.12.6, released 2026-10-09. The full release history is on /changelog, and every release, major, minor or patch, lists the figures it moved.
07 · API access
Keys, rate limits, idempotency, errors, client libraries.
The free Developer Sandbox lets you generate an evaluation key to try the API and MCP server, no card required. It is for evaluation, not production. Pass the key as Authorization: Bearer <key> on every request. For production access, book a demo and we run a pilot, moving to an annual contract if it works.
30 requests per minute per API key, on a 60-second sliding window. Cached responses (24h) do not count against your monthly quota but do count against the per-minute rate limit. Rate-limit state is exposed in the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers.
Pass an Idempotency-Key header on POST endpoints. Same key plus same body within 24 hours replays the cached response instead of recomputing. The response carries X-Idempotency-Replayed: true on a cache hit and false on the original call. Useful for safe retries in network failure scenarios.
cURL works against any endpoint directly. Code samples in Node, Python, and Go are on /docs/api-reference. The MCP server, included with your plan, lets you call the API from AI assistants and any MCP-compatible client.
All endpoints return RFC 7807 problem+json on error: { type, title, status, detail, instance }. 401 for missing or invalid key; 403 for plan-gated endpoints; 404 for unknown area; 422 for validation failures (including AI-side failures on /v1/query, which surface as { type: "llm_error", status: 422 } rather than 500); 429 for rate-limit; 5xx for our problem. Every response carries an X-Request-Id you can quote when contacting support.
A boolean response header that echoes whether the response came from the idempotency cache. true = cached replay of an earlier call with the same Idempotency-Key + body. false = freshly computed. Useful for end-to-end testing and for knowing whether you are paying compute for a request.
08 · Plans and buying
How OneGoodArea is packaged, priced, and bought.
One path: a free Developer Sandbox (500 calls a month, evaluation only, no card), a 40-day pilot on one workflow, then a licence. A platform licence covers showing OneGoodArea inside your product with attribution, annual, in two scopes: Build (from £2,000 a month: Signals, Scores, the MCP server, bulk mapping, production use) and Decision (from £5,000 a month: adds Intelligence, Monitor with portfolios and webhooks, batch scoring, saved presets and cohorts, IP allowlisting). A data partnership adds redistribution rights for the feeds and exports your customers keep, as a licence fee or revenue share. Regulated buyers can add Assured: a provenance pack for your model file, a signed DPA and dedicated support, on a custom annual contract. Full detail at /pricing.
By reach, not by API call: the records you enrich or the end customers you serve. Licences are annual contracts with a floor of £2,000 a month. Usage limits exist to protect the platform, but they are not the headline. There is no self-serve checkout; you buy it like infrastructure.
Book a demo. We look at your use case, then run a pilot on one real workflow, moving to an annual contract if it works. The Developer Sandbox is free if you just want to evaluate the API or explore the MCP server first.
Forty days, hands-on, against one real workflow and one success metric agreed up front. Licence terms are drafted by day 30, so you decide on the evidence, not a demo. If it works, you move onto a platform licence or a data partnership.
It is for evaluation and prototyping, not production, customer-facing, or revenue-generating use: 500 calls a month across the API and the MCP server, with 100 natural-language questions, so you can test the integration. For a production evaluation we run a pilot, and production use is licensed under a platform licence or a data partnership.
Built in today: IP allowlisting, training capture off by default, a methodology version on every response and a published changelog of every release. Data handling, retention, and our sub-processors are documented in the public privacy, data, and security pages, and for your review we will sign a DPA and complete your security questionnaire. Formal certifications like SOC 2 and ISO 27001 are on the roadmap as we grow into larger regulated deals.
09 · Account
Sign in, password reset, account deletion, RBAC roles.
Sign up with email and password at /sign-up, or use Google. We send a verification email; you must verify before generating an evaluation key on the free Developer Sandbox.
Go to /forgot-password, enter the email you signed up with, and we send a reset link. The link expires in 1 hour. If you do not receive the email within a few minutes, check spam, then contact operation@onegoodarea.co.uk.
Email operation@onegoodarea.co.uk with the subject "Account deletion" and we process the request within 48 hours. Deletion removes your user row, your API keys (revoked immediately), and your org membership. Org-level data persists if other members remain; sole owners of an org should transfer ownership first.
Three tiers: owner, admin, member. Owner can do everything, including billing, members, white-label, and IP allowlists. Admin can manage members, presets, and peer cohorts, but not billing. Member can call the API with their issued key and view reports, but cannot manage shared org state.
We read every email that lands at operation@onegoodarea.co.uk and we usually reply within one business day.