Vepler logo
v3.0.0 Breaking change

Free search autocomplete, a charged retrieve step, and billing transparency

Search suggest serves a free candidate set with a search_id, full records come from a charged retrieve step, and responses carry credit headers, rate limits and spend caps.

Changed

  • GET /v1/search/suggest now serves a candidate set when a query narrows to 100 or fewer strict matches. Rows carry a compact discovery projection (id, title, main_text, type, source, score, relevanceScore, uprn and the matched-substring arrays) plus a server-issued search_id and a set_complete flag. On candidate-set rows description, secondary_text, location, postcode, metadata and highlights are not returned: take the chosen suggestion's uprn to the retrieve step for the full record, or adopt @vepler/sdk/address-search, which implements the whole flow. Queries above 100 matches keep the previous full rows with set_complete: false.
  • Suggest itself is now free, and the charge moves to selection. The new retrieve step at /v1/search/retrieve takes a required uprn and an optional search_id, returns the full address record (line_1 to line_3, post_town, county, postcode, formatted, coordinates and classification_code), and charges per retrieved record at the standard address rate. Repeat retrievals of the same UPRN inside a billing window are charged once. Passing search_id from a suggest response narrows within the cached set server-side; sets stay live for ten minutes.
  • Charged responses carry billing transparency headers: X-Credits-Charged, X-Credits-Balance and X-Already-Charged when charge-once deduplication applied. An optional X-Search-Session request header (UUID) attributes requests to your own end-user sessions in the request logs.
  • Per-tenant limits protect spend. Suggest is limited to 600 requests per minute per tenant and billable routes to 50,000 credits per UTC day by default; both are adjustable per account. Over a limit the API returns 429 with a Retry-After header and error code rate_limit_exceeded. Requests with no spendable credit are refused up front with 402 and error code insufficient_credits, before any billable work runs.
  • The SDK gains @vepler/sdk/address-search: createAddressSearch() is a framework-agnostic, headless autocomplete controller with a 250 ms debounce, local narrowing of complete candidate sets on extending keystrokes, one charged retrieve per selection, and parsed billing headers on every result.
  • building._provenance on POST /v1/property/query is licence-gated: raw per-source building values return only when explicitly requested through the attributes parameter by a caller holding the source-data licence.

Fixed

  • Address strings across GET /v1/address/uprn/{uprn}, the property endpoints and search come from one canonical composer, so the same UPRN formats identically everywhere. Lookups return the full building number and suffix, for example 55A, and premises identified by an organisation or building name render that name rather than a bare street line.
  • granularity=street queries on GET /v1/search/suggest resolve without a comma: west street sheffield finds West Street in Sheffield. Queries that already resolved are unchanged.
  • Licensed callers who opt into sources or _provenance on POST /v1/property/query receive those fields on every path.

Affected endpoints