@vepler/sdk 3.0.0 → 5.28.1

package/src/sdk/property.ts

@@ -7,6 +7,7 @@ import { propertyGetProperties } from "../funcs/propertyGetProperties.js";
 import { propertyGetPropertiesByLocation } from "../funcs/propertyGetPropertiesByLocation.js";
 import { propertyGetPropertiesBySlugs } from "../funcs/propertyGetPropertiesBySlugs.js";
 import { propertyGetPropertiesBySource } from "../funcs/propertyGetPropertiesBySource.js";
+import { propertyGetPropertyAttributes } from "../funcs/propertyGetPropertyAttributes.js";
 import { propertyGetPropertyTiles } from "../funcs/propertyGetPropertyTiles.js";
 import { propertySearchProperties } from "../funcs/propertySearchProperties.js";
 import { ClientSDK, RequestOptions } from "../lib/sdks.js";
@@ -16,10 +17,10 @@ import { unwrapAsync } from "./types/fp.js";
 
 export class Property extends ClientSDK {
   /**
-   * Aggregate property statistics within a geographic area
+   * Aggregate property statistics for an area
    *
    * @remarks
-   * Execute real-time aggregations (counts, averages, distributions) over property data within a specified geographic boundary. Limited to areas ≤500 km² for reliable performance. Returns computed statistics without individual property documents.
+   * Counts, averages and distributions calculated over the properties in an area, without returning the properties themselves. Use it for market summaries and charts where a full result set would be wasteful. The areas may cover 500 km² in total at most, and a request may carry up to 10 aggregations.
    */
   async aggregateProperties(
     request?: shared.PropertyAggregateRequest | undefined,
@@ -33,10 +34,10 @@ export class Property extends ClientSDK {
   }
 
   /**
-   * Get properties by property IDs
+   * Get properties by property ID
    *
    * @remarks
-   * Retrieve property data using comma-separated property identifiers
+   * Returns one property per property ID supplied, separated by commas. Reach for it when you already hold property IDs from an earlier response; look properties up by location ID when you hold a UPRN instead.
    */
   async getProperties(
     request: operations.GetPropertiesRequest,
@@ -50,10 +51,10 @@ export class Property extends ClientSDK {
   }
 
   /**
-   * Get properties by location IDs
+   * Get properties by location ID
    *
    * @remarks
-   * Retrieve property data using comma-separated location identifiers
+   * Returns one property per location ID supplied, which in Great Britain is the Unique Property Reference Number (UPRN). Pass several at once by separating them with commas. Use `attributes` to choose what comes back; without it you get the default set of identity and address fields. Add `monitor` to also monitor the properties it returns, for a whole number of months or `true` for one; the response then carries a short `monitoring` object and is otherwise unchanged.
    */
   async getPropertiesByLocation(
     request: operations.GetPropertiesByLocationRequest,
@@ -67,10 +68,10 @@ export class Property extends ClientSDK {
   }
 
   /**
-   * Get properties by slugs
+   * Get properties by slug
    *
    * @remarks
-   * Retrieve property data using an array of property slugs
+   * Returns the properties matching a list of address slugs, the URL-safe form carried in each property's `slug` field. Up to 1,000 slugs per request.
    */
   async getPropertiesBySlugs(
     request?: shared.PropertyBySlugsRequest | undefined,
@@ -84,10 +85,10 @@ export class Property extends ClientSDK {
   }
 
   /**
-   * Get properties by source IDs
+   * Get properties by source ID
    *
    * @remarks
-   * Retrieve property data using comma-separated source identifiers (e.g., provider-a::123)
+   * Returns the property behind each source ID supplied, separated by commas. A source ID is written `provider::key`, naming the provider and its own identifier for the record, so this is the way back from a provider's listing reference to the property it belongs to.
    */
   async getPropertiesBySource(
     request: operations.GetPropertiesBySourceRequest,
@@ -100,11 +101,26 @@ export class Property extends ClientSDK {
     ));
   }
 
+  /**
+   * Get the property attribute catalogue
+   *
+   * @remarks
+   * Lists every attribute the property endpoints can return, with its dotted path, type, the billing tier it puts a request into and any extended permission it needs, alongside the field names, comparators and sort fields that `POST /v1/property/query` accepts. Read it to build a request without guessing, and to price one before sending it. This endpoint is free to call.
+   */
+  async getPropertyAttributes(
+    options?: RequestOptions,
+  ): Promise<shared.PropertyAttributeCatalogue> {
+    return unwrapAsync(propertyGetPropertyAttributes(
+      this,
+      options,
+    ));
+  }
+
   /**
    * Get property map tiles
    *
    * @remarks
-   * Retrieve property data as Mapbox Vector Tiles (MVT) for map visualisation. Supports up to 10,000 properties per tile via Elasticsearch native MVT. Filter properties using the query parameter with PropertyQueryOperator format. Tiles follow the standard Web Mercator (EPSG:3857) z/x/y scheme.
+   * Returns properties as a Mapbox Vector Tile, ready to drop into a map style. Tiles follow the standard Web Mercator z/x/y scheme, so a map library requests them by URL template. A tile carries up to 10,000 properties; use `mode=density` at low zoom, where a grid of counts replaces the individual properties and nothing is dropped. Narrow what a tile draws with `query` and `area`, and choose what each feature carries with `attributes`.
    */
   async getPropertyTiles(
     request: operations.GetPropertyTilesRequest,
@@ -118,13 +134,10 @@ export class Property extends ClientSDK {
   }
 
   /**
-   * Query properties with advanced filters
+   * Search properties
    *
    * @remarks
-   * Search for properties using location, price, and other criteria. By default, only residential properties are returned. To include commercial properties, add a `propertyCategory` condition to your query:
-   *
-   * - Commercial only: `{ "field": "propertyCategory", "comparator": "eq", "value": "commercial" }`
-   * - All categories: omit the default by adding `{ "field": "propertyCategory", "comparator": "exists" }`
+   * Searches properties inside one or more areas, narrowed by any combination of attributes: price, bedrooms, energy rating, market status and the rest of the catalogue at `GET /v1/property/attributes`. Only residential properties are returned, and a `propertyCategory` condition cannot widen that, so a query asking for commercial properties matches nothing. A page may hold up to 10,000 properties, and `limit` plus `offset` may not exceed 10,000 either, so reach a deeper result set by narrowing the area rather than paging on; a request beyond that depth is rejected instead of being quietly answered with a different page. The optional `monitor` parameter registers every property the query matches, which is the whole match set rather than the page returned, for monitoring billed monthly per property. That registration runs in the background and needs an active property_monitoring licence grant, and the response carries a `monitoring` receipt describing what happened to it.
    */
   async searchProperties(
     request?: shared.PropertyQueryRequest | undefined,

package/src/sdk/prosperity.ts

@@ -13,11 +13,7 @@ export class Prosperity extends ClientSDK {
    * Get the Prosperity Index for one or more small areas
    *
    * @remarks
-   * Returns the Vepler Prosperity Index for one or more small-area codes — a composite 0-100 economic-prosperity score with national decile (1-10) and percentile. Pass a single code (e.g. `E01000001`) or a comma-separated list (up to 100). Each result is self-describing, carrying its own `geographicCode`, so multi-code lookups can be mapped back by the caller.
-   *
-   * The score breaks down into four weighted dimensions (income, housing, employment, living standards) and the curated underlying indicators (19 ONS/MHCLG measures) that feed them, each with display value, national median/mean, percentile and source attribution. England & Wales areas also carry the ONS OAC 2021 geodemographic classification (null for Scotland and Northern Ireland, which have no OAC).
-   *
-   * Codes with no persisted score are silently omitted from the result set — a request for valid-but-unscored codes returns an empty list, not a 404.
+   * Returns the Vepler Prosperity Index for one or more small areas: a composite score from 0 to 100, with the area's national decile from 1 to 10 and its national percentile. Each result carries its own `geographicCode`, breaks the score down into four weighted dimensions (income, housing, employment and living standards) and up to 19 curated indicators behind them, and adds the Office for National Statistics Output Area Classification for areas in England and Wales. Pass a single code or a comma-separated list of up to 100; codes that hold no score are left out of the response rather than reported as errors, so a request for valid but unscored codes returns an empty list.
    */
   async get(
     request: operations.GetProsperityRequest,

package/src/sdk/safety.ts

@@ -15,12 +15,10 @@ import { unwrapAsync } from "./types/fp.js";
 
 export class Safety extends ClientSDK {
   /**
-   * Get crime data catalog entries for a single country
+   * Get crime data availability for a single country
    *
    * @remarks
-   * Returns every catalog entry for the supplied country, newest period first. Filter by granularity with `periodType=yearly|monthly`.
-   *
-   * Period strings are normalised to public form (`YYYY` for yearly, `YYYY-MM` for monthly).
+   * Return one entry per period held for the supplied country, newest period first, each saying whether that period has been ingested. Narrow the result to one granularity with `periodType=yearly` or `periodType=monthly`. Periods come back as `YYYY` for yearly entries and `YYYY-MM` for monthly ones.
    */
   async getCatalogByCountry(
     request: operations.GetCatalogByCountryRequest,
@@ -37,7 +35,7 @@ export class Safety extends ClientSDK {
    * Get monthly crime category counts within a radius
    *
    * @remarks
-   * Aggregated monthly crime counts by category for the area within `radius` metres of `(latitude, longitude)`. Returns up to 12 months of data ending at the most recent month with significant reporting in the area. Months with no significant reporting are omitted.
+   * Count crimes by category and month for the area within `radius` metres of a point. The response covers the 12 months ending at the most recent month with significant reporting in that area, oldest month first, and leaves out months with no recorded incidents. Use it to chart how an area's crime mix moves over a year without pulling every incident.
    */
   async getCrimeAreaStats(
     request: operations.GetCrimeAreaStatsRequest,
@@ -54,11 +52,7 @@ export class Safety extends ClientSDK {
    * Get crime incidents near a point
    *
    * @remarks
-   * Retrieve individual crime incidents recorded within `radius` metres of `(latitude, longitude)`. Data is sourced from UK police open data (street-level recorded crime) covering England and Wales. Incident locations are anonymised by the provider to a nearby map point (accurate to ~150m). Data is published monthly with an approximate 2-month lag.
-   *
-   * The response is always clipped to a six-month window. When `date` (YYYY-MM) is supplied, the window anchors at that month (or the most recent month with significant reporting, whichever is sooner). When omitted, the window anchors on the latest significant reporting month for the area.
-   *
-   * Responses are hard-capped — when the cap is hit, `summary.truncated` is `true`; narrow the radius or date window to see the full result.
+   * Return the individual crime incidents recorded within `radius` metres of a point, covering England and Wales. Incident locations are anonymised at source to a nearby map point, accurate to roughly 150m, and are published monthly around two months in arrears. The response always covers six months: supplying `date` ends that window at the month given, or at the most recent month with significant reporting if that is earlier, and leaving `date` out ends it at the most recent month with significant reporting in the area. A single request returns at most 5,000 incidents, and sets `summary.truncated` to `true` when it hits that cap, so narrow the radius or the date window to see the rest.
    */
   async getCrimeIncidents(
     request: operations.GetCrimeIncidentsRequest,
@@ -75,7 +69,7 @@ export class Safety extends ClientSDK {
    * Get per-point monthly crime category counts within a radius
    *
    * @remarks
-   * Same time window as `/stats` but groups by the exact anonymised reporting point, so multiple incidents at the same coordinate are returned separately. Useful for rendering heat-map style overlays where each incident point matters.
+   * Count crimes by category and month over the same 12-month window as `/stats`, but grouped by each anonymised reporting point rather than for the area as a whole. Every point inside the radius gets its own entry per month, with the coordinates needed to place it on a map, which is what heat-map style overlays require.
    */
   async getCrimePointStats(
     request: operations.GetCrimePointStatsRequest,
@@ -89,15 +83,10 @@ export class Safety extends ClientSDK {
   }
 
   /**
-   * Get crime metrics for one or more geographic areas
+   * Get crime metrics for one or more geographic areas (England only)
    *
    * @remarks
-   * Aggregated crime metrics for one or more geographic codes (LSOA / ward / authority) across one or more periods. Two modes:
-   *
-   * - **Individual areas** (default): one response row per `(geographicCode, period)` combination.
-   * - **Merged areas** (`mergeAreas=true`): one response row per period, with counts and population summed across every requested geography.
-   *
-   * Period selection is either explicit (`periods=YYYY-MM,YYYY-MM`) or by range (`startDate=YYYY-MM` + `endDate=YYYY-MM`); the two modes are mutually exclusive. Each requested period optionally drives a lookback time-series controlled by `months` (default 12). Empty result sets are returned as `data: []` with `total_count: 0` — never a 204.
+   * Return scored crime metrics for one or more areas, identified by Lower Layer Super Output Area (LSOA), ward or authority code, across one or more months, each with a per-category breakdown and an optional monthly history. Coverage is England only: the scored area metrics behind this endpoint hold English geographies alone, so codes in Wales, Scotland or Northern Ireland come back as `data: []`, and incident-level data for England and Wales lives at `/v1/safety/crime` instead. By default the response carries one row per area and month; with `mergeAreas=true` it carries one row per month, with counts and population summed across every requested area and scores, percentiles and trends set to null because they cannot be combined across areas. Choose the months either explicitly with `periods=YYYY-MM,YYYY-MM` or as a range with `startDate` and `endDate`, never both, and set how far each row's history reaches back with `months`, which defaults to 12. An empty result comes back as `data: []` with `total_count: 0`, never as a 204.
    */
   async getGeographyMetrics(
     request: operations.GetGeographyMetricsRequest,
@@ -114,9 +103,7 @@ export class Safety extends ClientSDK {
    * List crime data availability by country
    *
    * @remarks
-   * Returns the set of countries with crime data and, for each, the yearly and monthly periods that have been ingested. Use `GET /v1/safety/catalog/{country}` to get the full per-period catalog rows.
-   *
-   * Period strings are normalised to public form (`YYYY` for yearly, `YYYY-MM` for monthly) so they can be round-tripped into other safety queries without translation.
+   * List the countries that hold crime data and, for each one, the yearly and monthly periods that have been ingested, most recent first. Call this before a dated query to find out which periods can be asked for; the per-country endpoint breaks the same information out into one entry per period. Periods come back as `YYYY` for yearly entries and `YYYY-MM` for monthly ones, ready to pass straight into the other safety endpoints.
    */
   async listCatalogCountries(
     request?: operations.ListCatalogCountriesRequest | undefined,

package/src/sdk/schools.ts

@@ -12,17 +12,17 @@ import { schoolsListProfiles } from "../funcs/schoolsListProfiles.js";
 import { schoolsQuerySchools } from "../funcs/schoolsQuerySchools.js";
 import { schoolsQuerySchoolsBySource } from "../funcs/schoolsQuerySchoolsBySource.js";
 import { ClientSDK, RequestOptions } from "../lib/sdks.js";
-import { Changelog } from "./changelog.js";
 import { CoverageMatrix } from "./coveragematrix.js";
 import { Frameworks } from "./frameworks.js";
 import * as operations from "./models/operations/index.js";
 import * as shared from "./models/shared/index.js";
+import { SDKChangelog } from "./sdkchangelog.js";
 import { unwrapAsync } from "./types/fp.js";
 
 export class Schools extends ClientSDK {
-  private _changelog?: Changelog;
-  get changelog(): Changelog {
-    return (this._changelog ??= new Changelog(this._options));
+  private _changelog?: SDKChangelog;
+  get changelog(): SDKChangelog {
+    return (this._changelog ??= new SDKChangelog(this._options));
   }
 
   private _coverageMatrix?: CoverageMatrix;
@@ -39,7 +39,7 @@ export class Schools extends ClientSDK {
    * Autocomplete schools by name
    *
    * @remarks
-   * Type-ahead lookup over the school name. Combines a fast prefix match with a trigram similarity fallback so common typos still surface results. Cached for 1h per (query, onlyOpen) tuple.
+   * Suggests schools as someone types a name. Names that start with the query come first, then close matches, so a small typo still returns results. The query must be at least 2 characters and at most 25 suggestions are returned. Results are cached for an hour.
    */
   async autocomplete(
     request: operations.AutocompleteSchoolsRequest,
@@ -56,7 +56,7 @@ export class Schools extends ClientSDK {
    * Compare metrics across schools
    *
    * @remarks
-   * Build a side-by-side comparison matrix of metric values for 2–50 schools across one or more metric codes. Defaults to the current academic year and the 'all' cohort.
+   * Returns the same metric codes for 2 to 50 schools side by side, keyed by school and then by code, so a table can be built from one call. Reads the most recent academic year on record unless `academicYear` says otherwise, and covers all pupils rather than a narrower group. Schools and codes with nothing published are left out of the response.
    */
   async compareMetrics(
     request?: shared.MetricsCompareRequest | undefined,
@@ -73,7 +73,7 @@ export class Schools extends ClientSDK {
    * Aggregate a metric across geography
    *
    * @remarks
-   * Aggregate a single metric across local authorities, regions, or nationally. Optional `schoolTypes` filter (comma-separated) limits the contributing schools. Capped at 1000 area rows.
+   * Summarises one metric across areas rather than schools, giving the mean, minimum, maximum and standard deviation for each area along with how many schools contributed. Group by local authority, by region, or into a single national row. `schoolTypes` narrows which schools count towards the totals. Rows come back most-contributing first, and at most 1000 of them.
    */
   async getGeographicAggregation(
     request: operations.GetGeographicMetricAggregationRequest,
@@ -90,7 +90,7 @@ export class Schools extends ClientSDK {
    * Get school metrics
    *
    * @remarks
-   * Retrieve metrics for specified schools using metric codes or predefined profiles. Supports both point-in-time and time series queries.
+   * Returns published figures for one or more schools: results, attendance, finance, pupil characteristics and destinations. Name the figures either with `metricCodes` or with a `profile`, never both. By default the response covers a single academic year; set `timeseries=true` with `startYear` and `endYear` for a value per year instead. `includeDefinitions` returns what each code means and `includeComparisons` returns national, regional and similar-school averages beside it.
    */
   async getMetrics(
     request: operations.GetSchoolMetricsRequest,
@@ -107,7 +107,7 @@ export class Schools extends ClientSDK {
    * Get school by id
    *
    * @remarks
-   * Retrieve a single school by its internal identifier.
+   * Returns one school by its identifier in this API. Use `attributes` to add aggregate blocks such as `inspections`, or to trim the response to the fields you need.
    */
   async getSchoolById(
     request: operations.GetSchoolByIdRequest,
@@ -124,7 +124,7 @@ export class Schools extends ClientSDK {
    * Get school by provider and key
    *
    * @remarks
-   * Retrieve a single school by its source register identifier. Provider codes: `dfe` (England + Wales URNs), `welshgov` (Wales School Number), `seed` (Scottish SEED), `deni` (NI DE Reference), `dept_edu_ie` (Irish Roll Number).
+   * Returns one school by the identifier its own national register uses, for callers holding a register key rather than an identifier from this API. The registers are `dfe` for England and cross-border Welsh URNs, `welshgov` for the Welsh Government school number, `seed` for the Scottish SEED code, `deni` for the Northern Ireland reference and `dept_edu_ie` for the Irish roll number. Use `attributes` to add aggregate blocks or trim the fields returned.
    */
   async getSchoolBySource(
     request: operations.GetSchoolBySourceRequest,
@@ -141,7 +141,7 @@ export class Schools extends ClientSDK {
    * List metric profiles
    *
    * @remarks
-   * Get a list of all available metric profiles with their descriptions and metric counts
+   * Lists the metric profiles accepted by the `profile` parameter on `/v1/schools/metrics`, with what each one covers and how many metric codes it expands to. Read this first to avoid naming codes by hand.
    */
   async listProfiles(
     options?: RequestOptions,
@@ -156,9 +156,7 @@ export class Schools extends ClientSDK {
    * Query schools with filters and optional catchment enrichment
    *
    * @remarks
-   * Search for schools by country/region, type, status, rating, authority, postcode, free-text, or geography (radius via `near` or bounding box via `within`). Supports pagination via `limit`/`offset` and ordering via `orderBy`/`order`.
-   *
-   * **Catchment enrichment.** Set `catchmentReference` (with either `uprn` or `point`) to embed a five-tier catchment match per school. Each school gains an inline `catchment` block (`matchBasis` + `verdict`) and the response gains a `meta.catchment` block describing which tiers were applied / skipped and any coverage warnings. When `catchmentReference` is supplied with `uprn` but no `near` or `within`, the server defaults `near` to the property point with a 10 km radius.
+   * Searches schools by country and region, by type, status, rating, authority, postcode or free text, or by geography with `near` for a radius and `within` for a bounding box. Page through the results with `limit` and `offset`, up to 100 schools per page. Supplying `catchmentReference`, with either a `uprn` or a `point`, also tests every returned school against that property: each one gains a `catchment` block saying why it matched and how firmly, and the response gains a `meta.catchment` block saying which kinds of evidence were used, which were not and why. When `catchmentReference` is supplied without `near` or `within`, the search is centred on the property with a 10 km radius.
    */
   async querySchools(
     request?: operations.QuerySchoolsRequestBody | undefined,
@@ -175,7 +173,7 @@ export class Schools extends ClientSDK {
    * Batch fetch schools by provider keys
    *
    * @remarks
-   * Retrieve multiple schools from a single source register by their provider-scoped keys. Maximum 500 keys per request. Keys that do not match are silently omitted.
+   * Looks up several schools in one national register in a single call, by the keys that register uses. At most 500 keys per request. Keys that match no school are left out of the response rather than reported as errors, so compare the results against what was sent.
    */
   async querySchoolsBySource(
     request?: operations.QuerySchoolsBySourceRequestBody | undefined,

package/src/sdk/schoolscatchment.ts

@@ -16,7 +16,7 @@ export class SchoolsCatchment extends ClientSDK {
    * Per-school unified admission area
    *
    * @remarks
-   * Returns a school's admission boundary in whatever form the data supports, as one GeoJSON FeatureCollection: `polygon` features for hard designated catchments, plus a `distance_radius` feature (school centre `Point` + `radiusM`) when last year's furthest-admitted-pupil distance is known. Lets a client draw a polygon or a circle from a single call. Use `academicYear` to pin the radius year and `asOfDate` for historic polygons.
+   * Returns a school's admission area in whichever form the published data supports, as one GeoJSON FeatureCollection, so a map can be drawn from a single call. A `polygon` feature is a catchment area the authority publishes. A `distance_radius` feature is a circle around the school, sized by the distance to the furthest pupil it admitted, and carries that year's admission criteria and offer counts. Pass `academicYear` to pin the year the circle is drawn from and `asOfDate` to see earlier polygons.
    */
   async getAdmissionArea(
     request: operations.GetSchoolAdmissionAreaRequest,
@@ -33,7 +33,7 @@ export class SchoolsCatchment extends ClientSDK {
    * Per-school catchment geometry
    *
    * @remarks
-   * Returns a GeoJSON FeatureCollection of every catchment polygon currently effective for the school — one feature per `(catchment_type, source)` combination. Use `asOfDate` for historic queries (e.g. last year's catchment) and `catchmentType` to restrict to designated / priority / shared / feeder areas.
+   * Returns the catchment areas published for one school as a GeoJSON FeatureCollection, ready to draw on a map, with one feature per boundary in force. Pass `asOfDate` to see the boundaries as they stood on an earlier date, and `catchmentType` to keep only certain kinds, such as designated or priority areas.
    */
   async getBySchool(
     request: operations.GetCatchmentBySchoolRequest,
@@ -50,7 +50,7 @@ export class SchoolsCatchment extends ClientSDK {
    * Nationwide catchment ingest coverage
    *
    * @remarks
-   * Returns a per-tier histogram of LPA ingest status (how many LPAs are `loaded`, `discovered`, `not_started`, …) for polygons, outcomes, feeders and faith jurisdictions. Drives the public coverage page.
+   * Reports how much catchment data is loaded across a country, by counting local authorities at each stage of ingest. The counts are broken down by the four kinds of evidence behind a catchment match: published catchment areas, admission outcomes, feeder links and faith jurisdictions. Read it to see where a catchment answer will be firm and where it will fall back to distance.
    */
   async getCoverage(
     request?: operations.GetCatchmentCoverageRequest | undefined,
@@ -67,9 +67,7 @@ export class SchoolsCatchment extends ClientSDK {
    * Query schools with filters and optional catchment enrichment
    *
    * @remarks
-   * Search for schools by country/region, type, status, rating, authority, postcode, free-text, or geography (radius via `near` or bounding box via `within`). Supports pagination via `limit`/`offset` and ordering via `orderBy`/`order`.
-   *
-   * **Catchment enrichment.** Set `catchmentReference` (with either `uprn` or `point`) to embed a five-tier catchment match per school. Each school gains an inline `catchment` block (`matchBasis` + `verdict`) and the response gains a `meta.catchment` block describing which tiers were applied / skipped and any coverage warnings. When `catchmentReference` is supplied with `uprn` but no `near` or `within`, the server defaults `near` to the property point with a 10 km radius.
+   * Searches schools by country and region, by type, status, rating, authority, postcode or free text, or by geography with `near` for a radius and `within` for a bounding box. Page through the results with `limit` and `offset`, up to 100 schools per page. Supplying `catchmentReference`, with either a `uprn` or a `point`, also tests every returned school against that property: each one gains a `catchment` block saying why it matched and how firmly, and the response gains a `meta.catchment` block saying which kinds of evidence were used, which were not and why. When `catchmentReference` is supplied without `near` or `within`, the search is centred on the property with a 10 km radius.
    */
   async querySchools(
     request?: operations.QuerySchoolsRequestBody | undefined,

package/src/sdk/sdkchangelog.ts

@@ -0,0 +1,25 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { schoolsChangelogList } from "../funcs/schoolsChangelogList.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as shared from "./models/shared/index.js";
+import { unwrapAsync } from "./types/fp.js";
+
+export class SDKChangelog extends ClientSDK {
+  /**
+   * List Schools API changelog entries
+   *
+   * @remarks
+   * Lists the changes made to the shape of the Schools API, newest first, so a cached schema can be reconciled without reading release notes. Each entry carries a dated `objectVersion`, whether the change was `additive`, a `deprecation`, a `removal` or a `fix`, and which shapes or endpoints it touched. A deprecation also carries the sunset date that the `Sunset` header on the affected endpoint reports. Entries are never edited once published. Responses are cacheable for 1 hour.
+   */
+  async list(
+    options?: RequestOptions,
+  ): Promise<shared.ChangelogListResponse> {
+    return unwrapAsync(schoolsChangelogList(
+      this,
+      options,
+    ));
+  }
+}

package/src/sdk/search.ts

@@ -2,7 +2,6 @@
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */
 
-import { searchSearchRetrieve } from "../funcs/searchSearchRetrieve.js";
 import { searchSearchSuggest } from "../funcs/searchSearchSuggest.js";
 import { ClientSDK, RequestOptions } from "../lib/sdks.js";
 import * as operations from "./models/operations/index.js";
@@ -11,39 +10,10 @@ import { unwrapAsync } from "./types/fp.js";
 
 export class Search extends ClientSDK {
   /**
-   * Retrieve the full address record for a selected suggestion
+   * Autocomplete UK addresses and locations
    *
    * @remarks
-   * The selection step of the candidate-set search flow. Suggest responses are free and carry only a discovery projection (label + UPRN + match highlights); pass the chosen suggestion's `uprn` here to receive the full address record — address lines, postcode, coordinates and classification.
-   *
-   * Include the `search_id` from the suggest response to complete that search session; the retrieval is then recorded against it. Without a `search_id` (or with one that has expired or is unknown) the endpoint still works as a direct resolve and is recorded as its own transaction.
-   *
-   * This endpoint is charged per retrieved record. Repeat retrievals of the same UPRN within a billing window are charged once — see the `X-Already-Charged` response header.
-   */
-  async searchRetrieve(
-    request: operations.SearchRetrieveRequest,
-    options?: RequestOptions,
-  ): Promise<shared.SearchRetrieveResponse> {
-    return unwrapAsync(searchSearchRetrieve(
-      this,
-      request,
-      options,
-    ));
-  }
-
-  /**
-   * Autocomplete search for UK addresses and locations
-   *
-   * @remarks
-   * Simple autocomplete for UK properties and locations. Searches across Address and Location sources with fuzzy matching. Automatically detects query type (postcode, address, place name) and returns suggestions.
-   *
-   * Optionally accepts a geographic centre point (`lat`, `lng`) to make results proximity-aware:
-   * - `geo_mode=bias` (default): soft preference. The best textual matches near the point rank higher, but distant matches are still returned.
-   * - `geo_mode=restrict`: hard cutoff. Only address results within `radius_meters` of the point are returned.
-   *
-   * Proximity shapes the RANKING (bias) and membership (restrict) of the address results; pair it with `source=address` for the most predictable proximity behaviour. Suggest returns a discovery projection only — address rows carry the label, UPRN and match highlights, never coordinates, distance or classification. Retrieve a chosen suggestion (`GET /search/retrieve`) for the full record including coordinates.
-   *
-   * Candidate-set sessions: once a query narrows to a small exact match set, the response carries a `search_id` and slim address rows (label + UPRN + match highlights). Pass `search_id` back on subsequent keystrokes to narrow within that set without a new data fetch; when `set_complete` is true the response already contains the complete match set, so further narrowing can happen client-side. Suggest responses are not charged — charging applies when a full record is retrieved.
+   * Type-ahead search over UK addresses and locations, with fuzzy matching. It works out for itself whether the query is a postcode, an address or a place name, and returns suggestions in one list. Supplying a centre point (`lat` and `lng`) makes address results proximity-aware: `geo_mode=bias`, the default, is a soft preference that ranks nearby matches higher while still returning distant ones, and `geo_mode=restrict` is a hard cutoff that returns only results within `radius_meters` of the point. Proximity therefore changes the order of address results under `bias` and which ones appear at all under `restrict`; pair it with `source=address` for the most predictable behaviour. Suggestions are a discovery view: an address row carries its label, its UPRN and the match highlights, and never coordinates, distance or classification. Look the chosen UPRN up with `GET /v1/address/uprn/{uprn}` for the full record. Once a query narrows to a small exact match set the response also carries a `search_id`. Send it back on the next keystroke to narrow within that set rather than fetching again, and when `set_complete` is true the response already holds every match, so further narrowing can happen in the client. Suggest responses are not charged per request: each search session settles one small flat charge, and full-record lookups are charged by the address endpoints.
    */
   async searchSuggest(
     request: operations.SearchSuggestRequest,

package/src/sdk/sites.ts

@@ -20,13 +20,7 @@ export class Sites extends ClientSDK {
    * Aggregate sites
    *
    * @remarks
-   * Run aggregations (analytics) on the sites index with optional filters and geographic area filters.
-   *
-   * Supports 14 aggregation types including terms, stats, histogram, date_histogram, percentiles, and geotile_grid. Up to 10 aggregations per request with up to 2 levels of nesting (sub-aggregations).
-   *
-   * The response `aggregations` object is keyed by the `name` you provide in each aggregation definition. The result shape depends on the aggregation type — see the AggregationResult schema for details.
-   *
-   * Filter interaction is the same as the search endpoint: `filters` AND `query` AND any `area` filter.
+   * Summarise sites in bulk rather than listing them: counts by tenure, area statistics, distributions over time, map-tile groupings, and so on. The same filters and geographic areas as the search endpoint decide which sites are counted. There are 14 aggregation types, and a request may carry up to 10 aggregations, each nested up to two levels deep. Results come back keyed by the `name` given in each definition, so pick names that are unique within the request.
    */
   async aggregate(
     request?: shared.SiteAggregateRequest | undefined,
@@ -43,7 +37,7 @@ export class Sites extends ClientSDK {
    * Batch lookup sites by IDs
    *
    * @remarks
-   * Retrieve multiple sites by their composite identifiers in a single request (max 100). IDs that do not match any site are silently omitted from the response — check `total_count` against your input length to detect missing sites. Supports attribute selection to control which fields are returned.
+   * Retrieve up to 100 sites by identifier in a single request, choosing which fields come back with `attributes`. Identifiers that match nothing are left out of the response rather than raising an error, so compare `total_count` against the number of identifiers sent to spot the ones that were not found.
    */
   async findByIds(
     request?: shared.SiteBatchIdsRequest | undefined,
@@ -60,7 +54,7 @@ export class Sites extends ClientSDK {
    * Find sites by point
    *
    * @remarks
-   * Find land titles whose boundary polygon contains the given WGS84 (EPSG:4326) coordinate. This is a point-in-polygon spatial query — returns all titles at that location. Multiple overlapping titles are common (e.g. a freehold and leasehold at the same address). Returns up to 50 matching sites. Returns an empty list (not a 404) if no titles contain the point.
+   * Find every registered title whose boundary encloses a single coordinate, given as latitude and longitude in WGS84 decimal degrees. Overlapping titles at one spot are common, such as a freehold and a leasehold over the same building. Up to 50 sites come back, and a point inside no title returns an empty list rather than a 404.
    */
   async findByPoint(
     request?: operations.FindSitesByPointRequest | undefined,
@@ -77,7 +71,7 @@ export class Sites extends ClientSDK {
    * Find sites by property
    *
    * @remarks
-   * Find land titles that contain a specific property UPRN (Unique Property Reference Number). A property can belong to multiple titles (e.g. a flat in a freehold building will match both the leasehold and freehold titles). Returns up to 50 matching sites.
+   * Find the registered titles that cover a single addressable location. One location often sits under several titles at once, so a flat in a freehold block matches both its leasehold title and the freehold above it. Up to 50 sites come back, and a location with no titles returns an empty list rather than a 404.
    */
   async findByProperty(
     request: operations.FindSitesByPropertyRequest,
@@ -94,7 +88,7 @@ export class Sites extends ClientSDK {
    * Get site by ID
    *
    * @remarks
-   * Retrieve a single site by its composite identifier in `{country}:{registry}:{titleRef}` format (e.g. `GB:NPS:AGL123456`). Returns the full site object including boundary geometry, property statistics, planning data, scores, and area metrics. Requires a valid API key passed via the `Authorization: Bearer <key>` header.
+   * Retrieve one registered title by its identifier, which joins the country, the registry and the title number with colons, as in `GB:NPS:AGL123456`. This endpoint returns every attribute, including the boundary geometry, ownership, property statistics, planning statistics and area metrics.
    */
   async get(
     request: operations.GetSiteByIdRequest,
@@ -111,7 +105,7 @@ export class Sites extends ClientSDK {
    * Get properties in site
    *
    * @remarks
-   * Get all UPRNs (Unique Property Reference Numbers) linked to a specific site via spatial intersection with the Ordnance Survey AddressBase dataset. Returns an array of UPRN strings and the total count. Use these UPRNs with the Property API to fetch full property details.
+   * List the addressable locations that fall within one registered title, matched against the Ordnance Survey AddressBase dataset. The response carries the identifiers and how many there are; pass them to the Property API to fetch the full property records.
    */
   async getProperties(
     request: operations.GetPropertiesInSiteRequest,
@@ -128,15 +122,7 @@ export class Sites extends ClientSDK {
    * Get site boundary tiles
    *
    * @remarks
-   * Retrieve site boundaries as Mapbox Vector Tiles (MVT / application/x-protobuf) for map visualisation.
-   *
-   * Returns actual polygon geometries rendered from the `boundary` geo_shape field — not simplified or clustered points. Each feature in the tile includes properties specified by the `fields` parameter (defaults to siteId, titleRef, tenureType, status, areaSqm, locationCount, areaMetrics.prosperityDecile).
-   *
-   * **Zoom constraint:** Only available at zoom level 12 and above. Requests below zoom 12 return a 400 error — site polygons are too small and dense to render meaningfully at lower zoom levels.
-   *
-   * **Filtering:** Supports the same filter, query, and area parameters as the search endpoint, passed as JSON-encoded query parameters. Maximum 10,000 features per tile.
-   *
-   * **Caching:** Responses include `Cache-Control: public, max-age=30, s-maxage=60` headers. Suitable for use with Mapbox GL JS, MapLibre GL JS, or any MVT-compatible map renderer.
+   * Draw title boundaries on a map. Each tile comes back as a Mapbox Vector Tile (`application/x-protobuf`) carrying the real boundary polygons, not simplified shapes or clustered points, ready for MapLibre GL JS, Mapbox GL JS or any renderer that reads vector tiles. Tiles are served from zoom 12 upwards; below that the polygons are too small and too densely packed to draw usefully, and the request fails. A tile carries at most 10,000 features, and the same filter, query and area parameters as the search endpoint narrow what it holds. Responses carry `Cache-Control: public, max-age=30, s-maxage=60`, so a shared cache or CDN can serve repeat views.
    */
   async getTiles(
     request: operations.GetSiteTilesRequest,
@@ -153,18 +139,7 @@ export class Sites extends ClientSDK {
    * Search sites
    *
    * @remarks
-   * Search sites with advanced filters, geographic area filters, sorting, and pagination.
-   *
-   * **Filter interaction logic:**
-   * - `filters` (convenience) and `query` (advanced) are combined with AND logic — a site must match both.
-   * - Multiple `area` filters are combined with OR logic — a site matches if it satisfies any area filter.
-   * - Area filters are combined with AND against the other filters.
-   *
-   * **Spatial queries:** Supports polygon, multi-polygon, point+radius, containsPoint, and bounding box area types.
-   *
-   * **Attribute selection:** By default, the heavy `boundary` geometry is excluded. Pass `attributes: ["boundary"]` to include it.
-   *
-   * Requires a valid API key via `Authorization: Bearer <key>` header.
+   * Search registered titles by their attributes, by geographic area, or by both, with sorting and pagination. Area filters accept a polygon, a multi-polygon, a point with a radius, a point the boundary must enclose, or a bounding box; a site matches the area clause if it satisfies any one of the filters supplied, and that has to hold on top of `filters` and `query`. The `boundary` geometry is left out by default because of its size, so pass `attributes: ["boundary"]` to get site polygons back. Up to 1000 sites come back per request, from an offset of at most 100000.
    */
   async search(
     request?: shared.SiteQueryRequest | undefined,

package/src/sdk/streets.ts

@@ -9,10 +9,10 @@ import { unwrapAsync } from "./types/fp.js";
 
 export class Streets extends ClientSDK {
   /**
-   * Query streets with flexible identifiers
+   * Query streets by any identifier
    *
    * @remarks
-   * Query streets using USRN, UPRN, coordinates, name, or postcode. Optionally include properties and statistics.
+   * Returns the streets picked out by one of five identifiers: a USRN, a UPRN, a coordinate and radius, a name search, or a postcode. Each street comes back with its reference number, the coordinates of its start and end, and its name in each language it is recorded in. When an identifier matches no street, the response is an empty list with a `message` explaining which one missed.
    */
   async searchStreets(
     request?: shared.StreetQueryRequest | undefined,