Skip to main content
POST
/
v1
/
location
/
street
/
query
Query streets with flexible identifiers
curl --request POST \
  --url https://api.vepler.com/v1/v1/location/street/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "identifier": {
    "type": "usrn",
    "usrn": 21701338
  },
  "includeProperties": true,
  "includeStatistics": true,
  "propertyOptions": {
    "limit": 100,
    "offset": 0,
    "includeHistoric": false
  }
}
'
{
  "success": true,
  "streets": [
    {
      "usrn": 21701338,
      "descriptors": [
        {
          "streetDescription": "High Street",
          "locality": "Kensington",
          "townName": "London",
          "administrativeArea": "Greater London",
          "language": "ENG"
        }
      ],
      "streetStartLng": -0.1278,
      "streetStartLat": 51.5074,
      "streetEndLng": -0.128,
      "streetEndLat": 51.5076
    }
  ],
  "total": 1,
  "properties": [
    {
      "uprn": 10094639688,
      "paoText": "FLAT 12A",
      "saoText": "GROUND FLOOR",
      "paoStartNumber": 123,
      "saoStartNumber": 1
    }
  ],
  "statistics": {},
  "message": "<string>"
}

​
Overview

This endpoint allows you to search for street data using advanced filters. It’s useful for address autocomplete, location validation, and geographic analysis.

​
Request Body

{
  "query": {
    "street": "High Street",
    "town": "London",
    "postcode": "SW1A",
    "locality": "Westminster"
  },
  "filters": {
    "minProperties": 10,
    "hasPostcode": true
  },
  "pagination": {
    "limit": 20,
    "cursor": "eyJpZCI6MTIzfQ"
  }
}

​
Query Parameters

ParameterTypeRequiredDescription
query.streetstringNoStreet name to search for
query.townstringNoTown or city name
query.postcodestringNoFull or partial postcode
query.localitystringNoLocality or district
filters.minPropertiesnumberNoMinimum number of properties on street
filters.hasPostcodebooleanNoOnly return streets with postcodes
pagination.limitnumberNoResults per page (default: 20, max: 100)
pagination.cursorstringNoPagination cursor

​
Response

{
  "data": [
    {
      "id": "street_123456",
      "name": "High Street",
      "town": "London",
      "locality": "Westminster",
      "postcode": "SW1A 1AA",
      "coordinates": {
        "latitude": 51.5074,
        "longitude": -0.1278
      },
      "propertyCount": 145,
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-0.1278, 51.5074],
          [-0.1279, 51.5075]
        ]
      },
      "administrativeArea": {
        "localAuthority": "Westminster",
        "ward": "St James's",
        "constituency": "Cities of London and Westminster"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJpZCI6MTIzNDU2fQ",
    "hasMore": true,
    "total": 342
  }
}

​
Street Object Fields

FieldTypeDescription
idstringUnique street identifier
namestringStreet name
townstringTown or city
localitystringLocal area or district
postcodestringPrimary postcode for the street
coordinatesobjectCentre point of the street
propertyCountnumberNumber of properties on the street
geometryobjectGeoJSON LineString of street path
administrativeAreaobjectAdministrative boundaries

​
Example Requests

import { Vepler } from '@vepler/sdk';

const vepler = new Vepler({ apiKey: process.env.VEPLER_API_KEY });

const streets = await vepler.location.queryStreets({
  query: {
    street: 'Downing Street',
    town: 'London'
  }
});

console.log(streets.data);

const streets = await vepler.location.queryStreets({
  query: {
    postcode: 'SW1A'
  },
  filters: {
    minProperties: 20
  },
  pagination: {
    limit: 50
  }
});

​
Address Autocomplete

const autocomplete = await vepler.location.queryStreets({
  query: {
    street: userInput, // e.g., "High St"
    town: selectedTown
  },
  pagination: {
    limit: 10
  }
});

// Return street suggestions
const suggestions = autocomplete.data.map(street => ({
  label: `${street.name}, ${street.town} ${street.postcode}`,
  value: street.id
}));

​
Use Cases

Build intelligent address search with progressive disclosure:
// Step 1: User types postcode
const areas = await vepler.location.queryStreets({
  query: { postcode: 'SW1A' }
});

// Step 2: User selects street
const streets = await vepler.location.queryStreets({
  query: {
    postcode: 'SW1A',
    street: selectedStreet
  }
});

// Step 3: Get properties on street
const properties = await vepler.property.query({
  filters: { streetId: selectedStreetId }
});
Validate addresses before processing:
const validation = await vepler.location.queryStreets({
  query: {
    street: userAddress.street,
    town: userAddress.town,
    postcode: userAddress.postcode
  }
});

if (validation.data.length === 0) {
  throw new Error('Invalid address');
}
Analyze street-level data:
const areaStreets = await vepler.location.queryStreets({
  query: { postcode: 'SW1A' },
  filters: { minProperties: 10 }
});

const totalProperties = areaStreets.data.reduce(
  (sum, street) => sum + street.propertyCount,
  0
);

console.log(`Total properties in SW1A: ${totalProperties}`);

​
Pagination

Results are paginated using cursor-based pagination: 
let cursor = null;
const allStreets = [];

do {
  const response = await vepler.location.queryStreets({
    query: { town: 'London' },
    pagination: { limit: 100, cursor }
  });

  allStreets.push(...response.data);
  cursor = response.pagination.cursor;
} while (response.pagination.hasMore);

​
Rate Limits

  • 1000 requests per hour
  • 100 requests per minute

Get Properties by Location

Get properties for a specific location

Location Health Check

Check location service status

Authorizations

​
x-api-key
string
header
required

API Key authentication for Vepler API. Get your API key from the Vepler dashboard.

Body

application/json

Street query parameters with identifier and options

​
identifier
object
required

Street identifier - supports multiple query types

​
includeProperties
boolean
default:false

Include properties on the street

Example:

true

​
includeStatistics
boolean
default:false

Include street statistics

Example:

true

​
propertyOptions
object

Options for property listing

Response

Street data successfully retrieved

​
success
enum<boolean>
required
Available options:
true,
false
​
streets
object[]
required

Array of street details

​
total
number
required

Total number of streets found

Example:

1

​
properties
object[]

Properties on the street(s)

​
statistics
object

Statistics per street (keyed by USRN)

​
message
string

Additional information or warnings