---
title: "Score an area"
method: POST
path: "/v1/score"
tags: ["Scores"]
---

# Score an area

`POST /v1/score`

## Request

- Base URL: `https://api.onegoodarea.com`
- URL: `https://api.onegoodarea.com/v1/score`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Deterministic composite score for an area by preset or custom weights. Returns component dimensions + confidence.

## Query parameters

- `bundle` string
- `explain` 'true' | 'false'

## Request body

- object
  - `area` string, required: UK postcode or place name.
  - `preset` 'moving' | 'business' | 'investing' | 'research'
  - `preset_id` string: Org-saved preset ID. Mutually exclusive with preset/weights.
  - `explain` boolean
  - `bundle` string: Optional bundle ID to scope available signals.
  - `cohort` string: Slug of one of your org's cohorts. Transport, schools and amenities then rank against the cohort's members instead of neighbourhoods of the same kind; the response's `reference` says which was used. A cohort needs at least 30 areas with stored signals.

## Response `200`

Default Response

- object
  - `area` string, required
  - `preset` string, required
  - `score` number, required
  - `area_type` 'urban' | 'suburban' | 'rural', required
  - `rural_urban` string, required
  - `dimensions` object[], required
    - `key` string, required
    - `label` string, required
    - `score` number, required
    - `weight` number, required
    - `confidence` number, required
    - `reasoning` string, required
    - `confidence_reason` string, required
  - `confidence` number, required
  - `weights_source` 'preset' | 'custom', required
  - `reference` union, required
    - object
      - `kind` 'band', required
      - `band` 'urban' | 'suburban' | 'rural', required
    - object
      - `kind` 'cohort', required
      - `slug` string, required
      - `name` string, required
      - `areas` integer, required
    - object
      - `kind` 'national', required
      - `scope` 'GB', required
      - `reason` 'area_type_unavailable', required
  - `engine_version` string, required
  - `summary` string
  - `recommendations` string[]
  - `data_sources` string[]

## Other responses

- `400`: Default Response
- `401`: Default Response
- `403`: Default Response
- `404`: Default Response
- `422`: Default Response
- `429`: Default Response
- `500`: Default Response
- `502`: Default Response

## Changes

- **2026-10-20** `b318d28b3412`: 6 warning
  - added the new `nation_not_covered` enum value to the `anyOf[subschema #1]/code` response property for the response status `404`
  - added the new `nation_not_covered` enum value to the `anyOf[subschema #1]/code` response property for the response status `422`
  - added the new `nation_not_covered` enum value to the `anyOf[subschema #1]/reason` response property for the response status `404`
  - added the new `nation_not_covered` enum value to the `anyOf[subschema #1]/reason` response property for the response status `422`
  - …2 more

[Operation history](https://skmtc.dev/onegoodarea/apis/onegoodarea-api/changes/v1/score/post.md)

---

[API](https://skmtc.dev/onegoodarea/apis/onegoodarea-api.md) · [All operations](https://skmtc.dev/onegoodarea/apis/onegoodarea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onegoodarea/apis/onegoodarea-api/revisions/b318d28b3412?raw)