Responses and Data Types

Series endpoints return a JSON object containing request/release metadata and a list of metric series. This format supports grouped market measures, scalar rates, curves and forward paths without assigning one misleading unit or date to the whole response.

Response Envelope

Field	Type	Meaning
`request_id`	String	Server-generated identifier for this HTTP request; also returned as `X-Request-ID`.
`dataset`	String	Dataset selected by the request.
`release_id`	String	Family release actually read. Retain it for reproducibility.
`published_at`	Timestamp or null	Recorded publication time, not the date of each observation. Null when no publication timestamp is recorded.
`release_status`	String	State of the selected package. Normal serving requires `accepted`; use `/releases/current` to identify the current release.
`selection`	Object	Resolved selectors and supplied dates/node bounds, plus `mode` (`latest` or `range`).
`revision_policy`	String	Reminder that subsequent releases can revise values.
`series`	Array	Metric series represented on this page.
`next_cursor`	String or null	Continuation token, or null when this selection is complete.

The selection object is not a complete echo of every parameter. It does not contain credentials and does not currently echo metrics or page_size. Numeric query selectors can appear as strings in selection; numeric series dimensions are numbers. Do not infer a JSON Schema for one from the other.

The API generates request_id; this contract does not accept a caller-supplied request ID/reference. A new continuation request has its own request ID. The release ID and series ID have different purposes and are not request tickets.

Each Series

Field	Type	Meaning
`series_id`	String	Stable identity for a metric and its dimensions. Treat it as opaque.
`metric`	String	Machine-readable measure name.
`unit`	String	Such as `GBP`, `GBP/month`, `GBP/m2`, `GBP/km2`, `percent`, `basis_points`, `sales`, `homes` or `index`.
`frequency`	String	Native observation/snapshot frequency, `monthly` or `daily`.
`basis`	String	Interpretation category described below.
`dimensions`	Object	Node-specific selectors such as maturity, term or horizon; often empty for market/scalar series.
`availability`	Object	`status`, `from` and `to` for the stored series in the selected release.
`observations`	Array	Selected observations on this page; absent from `/coverage` responses.
`window_months`	Integer or null	Market calculation window where applicable. Yield instead discloses separate input windows.
`rental_window_months`, `capital_window_months`	Integers	Yield's distinct input windows.
`bounds_basis`	String	`modelled_uncertainty` for new-build differential bounds.
`history_capability`	String	Rates history type: retained observations, latest summary per release or saved snapshot only.
`empty_reason`	String, conditional	Why this page has no observations for a represented series.
`notice`	String, conditional	For example, requested dates extend beyond the stored history.

availability.status is available or not_available. Its bounds describe the release's stored support, not only the current page. Availability does not guarantee that every requested endpoint has a finite value. Read observations too.

Do not depend on array positions. Identify a series by series_id and inspect metric/dimensions. A curve contains multiple series with the same metric, one for each node. A multi-metric dataset may span pages, so absence from one page is not proof of exclusion.

Each Observation

Every observation contains period, value and status. value is a finite number, integer count or null. Optional metadata describes the relevant window, interval or reason.

Status/basis	Interpretation
`recorded_revisable`	Filtered summaries of recorded property activity; later source updates can revise them.
`estimated`	Modelled property-market measure, not an exhaustive directly observed statistic.
`observed`	Published rate/index/quoted benchmark observation.
`derived`	Calculation from reference observations, such as a rate spread.
`indicative`	Curve-derived/fitted reference, not an executable price.
`scenario`	Hypothetical future assumption; not an observed outcome or assigned probability.
`not_available`	Unsupported observation. Its value must not be displayed as zero.
`withheld_pending_review`	An estimate retained as a gap while it is reviewed. Its value is null; other periods and metrics can remain available.

basis is a series-level description; status belongs to an individual observation. A null value can retain the basis status and supply reason: missing_value or zero_denominator. Always test the value as well as the status.

Withheld Observations

An estimate under review retains its period and window metadata and includes reason and review_reference. For example, an observation may contain:

json

{
  "period": "2021-07",
  "value": null,
  "status": "withheld_pending_review",
  "reason": "movement_evidence_insufficient",
  "review_reference": "<review-reference>"
}

This is an illustrative observation fragment. Treat reason codes as extensible and the review reference as opaque. A withheld capital estimate also withholds a yield that depends on it; rent can remain available. HTTP 200 can include these gaps. The latest selection does not fall back to the last non-null value.

Nulls, Zero and Empty Arrays

value: 0 is a genuine zero, such as no recorded sales in an eligible window.
value: null with reason: zero_denominator means a ratio cannot be calculated, not a 0% ratio.
reason: missing_value means no finite published value was available for that observation.
reason: outside_supported_coverage identifies an unsupported estimate.
observations: [] with empty_reason: not_available means the series has no admitted observations in the release.
observations: [] with empty_reason: no_observations_in_requested_range means no observations match this selection; the series can still have history elsewhere.

A valid horizon selection may also yield an empty series array when no retained points match. Do not treat a missing/corrupt release as equivalent: that returns an error.

Market Observation Metadata

period_start and period_end are inclusive dates defining the window, not additional observations. period is the monthly endpoint.

For price bands, each observation contains band_lower_gbp, band_upper_gbp, lower_inclusive, upper_inclusive and band_basis. Outer bounds can be null. Equality with an internal boundary belongs to the higher band. Bounds change with the observation window.

Rent adds rental_observation_month and structure_observation_month. Capital adds capital_observation_month. Yield adds both input dates, input_month_gap, mixed_vintage, rental_period_start, rental_period_end, capital_period_start and capital_period_end. It deliberately does not pretend to have a single input window.

Development-size observations add total_deliveries_count, classified_deliveries_count, unclassified_deliveries_count and classification_coverage_pct. These coverage values concern the matching area/type/window, not a count of development sites.

New-build price differential observations may include a warnings array. An estimate retained under the historical-evidence policy uses:

json

{
  "code": "historical_evidence_below_current_threshold",
  "message": "Historical estimate retained with limited evidence; uncertainty may be elevated."
}

This object appears inside warnings on the affected observation, including its lower and upper estimate series. The observation remains estimated, not observed; its numeric value is unchanged. Display the warning alongside the figure. It is not a failed API request. The array is omitted when no warning applies.

Rates Observation Metadata

These fields appear only when applicable and supplied by the saved product. Do not require every field on every rate dataset.

Fields	Interpretation
`snapshot_date`	Curve/path snapshot date; distinct from future interval dates.
`interval_kind`	Type of economic rate interval.
`interval_start_month`, `interval_end_month`	Offset boundaries for an interval.
`interval_start_date`, `interval_end_date`	Actual interval dates.
`compounding`, `day_count`, `sonia_compounding`	Rate conventions; preserve the returned values.
`projection_start_month`, `projection_end_month`	Projection interval offsets.
`projection_start_date`, `projection_end_date`	Dates covered by the scenario point/interval.
`mortgage_latest_observation_date`, `svr_latest_observation_date`	Underlying monthly evidence dates.
`swap_2y_end_date`, `swap_5y_end_date`, `swap_10y_end_date`	End dates of the relevant forward swap intervals.
`matched_swap_as_of_date`	Date of the swap reference attached to a spread.
`observations_used`	Input observation count for a summary, where supplied.
`reference_basis`	`same_month_average` or `last_available_reference`; read this before comparing spreads.

Common numeric dimensions are tenor_months, term_years, horizon_month and, for BTL scenarios, ltv_pct. The chosen scenario or mortgage product is also identified in the response selection.

Numeric Precision and Presentation

Percent values are in percentage units: 4.25 means 4.25%. A value of 125 basis points means 1.25 percentage points. index is not a percentage. Currency uses GBP.

Counts are integers. Other values retain the published numeric precision; the contract does not round all amounts to whole pounds. JSON floating-point serialization can use scientific notation. Round for display only, and preserve underlying values when comparing releases or reproducing calculations.

The service returns Cache-Control: private, no-store. Do not introduce shared HTTP caching of authenticated responses. Any permitted application-level storage should retain release provenance and comply with your data licence.

Complete machine-readable examples accompany this documentation. They illustrate response structure with example release identifiers and historical values, not current market quotes or a guarantee of coverage.