Vepler API Documentation

@vepler/sdk is a typed client for every public endpoint, generated from the OpenAPI document. This page describes version 6.8.0.

npm install @vepler/sdk

Other package managers, runtimes and TypeScript settings are on Installation.

Create a client

import { SDK } from "@vepler/sdk";

const sdk = new SDK({ apiKeyAuth: process.env.VEPLER_API_KEY });

The SDK sends the key in the x-api-key header. Create keys in the dashboard. Create one client and reuse it.

Call an endpoint

const result = await sdk.property.getPropertiesByLocation({
  locationIds: "100023336956",
});

for (const property of result.data) {
  console.log(property.locationId, property.address?.displayAddress);
}

A method returns the parsed response body.

Names that are snake_case in the API are camelCase in the SDK: has_more becomes hasMore, total_count becomes totalCount and the geo_mode parameter becomes geoMode.
Some query parameters are typed as strings, including limit and offset on several GET endpoints such as getPropertiesByLocation: limit: "50". The request types show which.
The SDK sends X-API-Version: 2 with every request, so list endpoints that offer two formats return { object, url, data, has_more, total_count }, and the single-listing endpoints return the listing itself with "object": "listing". See Versions.

Methods

Methods are grouped by API area: address, airQuality, areas, avm, buildings, census, companies, connectivity, conservation, councils, energy, epc, floodRisk, geography, heritage, landConstraint, listings, metrics, planning, poi, property, prosperity, safety, schools, schoolsCatchment, search, sites, streets, system, titleDeeds and transactions. The package README lists every method. Some common ones:

Endpoint	Method
`GET /v1/property/{locationIds}`	`sdk.property.getPropertiesByLocation`
`POST /v1/property/query`	`sdk.property.searchProperties`
`GET /v1/address/postcodes/{postcode}`	`sdk.address.lookupPostcode`
`GET /v1/address/uprn/{uprn}`	`sdk.address.lookupUprn`
`POST /v1/address/resolve`	`sdk.address.resolveAddress`
`GET /v1/search/suggest`	`sdk.search.searchSuggest`
`POST /v1/planning/query`	`sdk.planning.searchPlanningApplications`
`POST /v1/listings/query/advanced`	`sdk.listings.queryListingsAdvanced`
`POST /v1/transactions/query`	`sdk.transactions.queryTransactions`

Errors

Methods throw on any 4xx or 5xx response.

import { SDKBaseError } from "@vepler/sdk/sdk/models/errors";

try {
  const address = await sdk.address.lookupUprn({ uprn: "100023336956" });
  console.log(address.formatted);
} catch (err) {
  if (err instanceof SDKBaseError) {
    console.error(err.statusCode, err.body);
  }
  throw err;
}

Error	Thrown when
`SDKBaseError`	The base class for every HTTP error. It has `statusCode`, `headers`, `body` (the raw text) and `rawResponse`.
A class for each documented error shape	The body matched the error shape that method documents. The parsed body is in `data$`.
`SDKError`	The status is one the method does not document.
`ResponseValidationError`	The response body did not match the shape the method documents, as with a 401 on methods that document one. `rawValue` holds the body.
`ConnectionError`, `RequestTimeoutError`, `RequestAbortedError`	The request did not complete. These are not `SDKBaseError`s.
`SDKValidationError`	Your arguments failed the SDK’s own checks, so nothing was sent. `instanceof SDKValidationError` is also true for a `ResponseValidationError`, so test `SDKBaseError` first.

The class depends on the response body, so branch on statusCode. Every class is exported from @vepler/sdk/sdk/models/errors. The error bodies themselves are described on Errors.

Retries

The SDK does not retry unless you configure it. Set a policy for the client, and override it for a single call with retries:

const sdk = new SDK({
  apiKeyAuth: process.env.VEPLER_API_KEY,
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 500,
      maxInterval: 10_000,
      exponent: 1.5,
      maxElapsedTime: 60_000,
    },
    retryConnectionErrors: false,
  },
});

await sdk.address.lookupUprn({ uprn: "100023336956" }, { retries: { strategy: "none" } });

Times are in milliseconds.
The SDK retries 429, 500, 502, 503 and 504 responses. Pass retryCodes with a call to change the list.
When a response has Retry-After, the SDK waits that long, up to maxInterval.
After maxElapsedTime it stops and throws the last error.
retryConnectionErrors: true also retries failed connections and timeouts. A request that timed out may still have completed and been charged, and a retry is charged again.
Without backoff, the defaults are initialInterval 500, maxInterval 60,000, exponent 1.5 and maxElapsedTime 3,600,000 (one hour).

A 429 from the daily credit cap does not clear until midnight UTC, so keep maxElapsedTime short.

Timeouts and cancellation

There is no timeout unless you set timeoutMs, on the client or on one call. A timeout throws RequestTimeoutError.

const sdk = new SDK({ apiKeyAuth: process.env.VEPLER_API_KEY, timeoutMs: 10_000 });

await sdk.address.lookupUprn({ uprn: "100023336956" }, { timeoutMs: 3_000 });

const controller = new AbortController();
setTimeout(() => controller.abort(), 3_000);
await sdk.address.lookupUprn({ uprn: "100023336956" }, { signal: controller.signal });

Aborting through signal throws RequestAbortedError. A call given a signal ignores timeoutMs.

Client options

Option	Purpose
`apiKeyAuth`	The API key, or an async function that returns it.
`serverURL`	The base URL. Defaults to `https://api.vepler.com`.
`timeoutMs`	Request timeout in milliseconds. None by default.
`retryConfig`	Retry policy. Off by default.
`httpClient`	An `HTTPClient` with your own `fetch`, or hooks that run before and after each request.
`debugLogger`	Logs each request and response, for example to `console`. The log includes the `x-api-key` header, so use it only on your own machine.
`userAgent`	Replaces the `user-agent` header the SDK sends.

Types

Request and response types are in @vepler/sdk/sdk/models/shared and @vepler/sdk/sdk/models/operations:

import type { PropertyListResponse } from "@vepler/sdk/sdk/models/shared";
import type { GetPropertiesByLocationRequest } from "@vepler/sdk/sdk/models/operations";

const request: GetPropertiesByLocationRequest = { locationIds: "100023336956", limit: "50" };
const page: PropertyListResponse = await sdk.property.getPropertiesByLocation(request);

These subpaths need moduleResolution set to nodenext, node16 or bundler.

Standalone functions

Every method is also a function you can import on its own, so a bundler can leave out the rest of the SDK. These functions return a result object rather than throwing on API and network errors:

import { SDKCore } from "@vepler/sdk/core.js";
import { addressLookupUprn } from "@vepler/sdk/funcs/addressLookupUprn.js";

const core = new SDKCore({ apiKeyAuth: process.env.VEPLER_API_KEY });
const res = await addressLookupUprn(core, { uprn: "100023336956" });

if (res.ok) {
  console.log(res.value.formatted);
} else {
  console.error(res.error);
}

Versions

Each SDK release takes the number of the API release it was generated from: 6.8.0 matches API 6.8.0. The SDK is not republished for every API release, so later additions, such as the streets cursor starting_after, are not in 6.8.0. Pin an exact version, as Installation explains. See Versions.

SDK

SDK Examples

TypeScript SDK

Create a client

Call an endpoint

Methods

Errors

Retries

Timeouts and cancellation

Client options

Types

Standalone functions

Versions

​Create a client

​Call an endpoint

​Methods

​Errors

​Retries

​Timeouts and cancellation

​Client options

​Types

​Standalone functions

​Versions

Create a client

Call an endpoint

Methods

Errors

Retries

Timeouts and cancellation

Client options

Types

Standalone functions

Versions