Vepler logo
v6.22.0 Breaking change

Choose the street dataset, and get richer street records with paging and per-street properties

Street lookups can read Ordnance Survey open data, the OS NGD or both, and street query returns a fuller street record with paging, field selection and properties on each street.

Changed

  • POST /v1/location/street/query, GET /v1/search/suggest with granularity=street and POST /v1/address/resolve (as options.dataset) take a dataset choice for street results. open reads Ordnance Survey open data published under the Open Government Licence, ngd reads the Ordnance Survey National Geographic Database, and open_then_ngd, the default, reads the open data first and turns to the NGD only when the open data cannot answer. Postcode lookups are answered from the NGD, so they return 400 under open. Street matches from suggest and resolve carry the dataset that supplied them.
  • Each item in data from POST /v1/location/street/query is a street record: id, usrn, country, the dataset that supplied it, name, descriptors (names in other languages), locality, town, district, county, postcodeDistrict, streetType, location, and the start and end coordinates where the dataset records them. To migrate, read street details from these fields on each record.
  • Read nameKind before showing name as a street name: name is a street name, while descriptor is a description the naming authority records in place of one, such as a road number. nameConfidence says whether the open data holds one name for the street (confident), several competing names (ambiguous) or none (absent, with name null). language on a descriptor is present only when the dataset records it.
  • Properties and counts now sit on each street. Set includeProperties to receive properties.uprns and properties.hasMore on every street, paged by propertyOptions (limit from 1 to 500, default 100, and offset), and set includeStatistics to receive propertyCount. propertyOptions.includeHistoric adds retired addresses and needs dataset set to ngd.
  • fields limits each record to the street fields you name. Under open_then_ngd, a named field the open data lacks for a street is filled from the NGD, provenance then shows which dataset supplied each field, and a name is always taken whole from one dataset.
  • Name searches are case-insensitive and return the closest matches first. Name, coordinate and postcode lookups page with starting_after, set to the id of the last street on the current page, and has_more reports whether another page follows.
  • attribution carries the acknowledgement you must show wherever the open-data street fields are displayed, and is present whenever a returned street includes open data.
  • POST /v1/location/street/query validates its request strictly: a field it does not recognise returns 400. To migrate, remove any fields outside the documented request.

Removed

  • The top-level properties and statistics blocks on the POST /v1/location/street/query response. Request includeProperties and includeStatistics instead and read properties and propertyCount on each street record.

Affected endpoints