Skip to main content

​
Overview

Most address and location workflows follow the same funnel:
  1. Discover — a user types into a search box and you surface matching addresses (autocomplete / typeahead, or a postcode lookup). Each keystroke may fire a request.
  2. Retrieve — the user picks one result and you fetch the full, verified record for it (the address detail, geocode, and identifiers).
The question every billing model has to answer is: how do you avoid charging for the same address twice across that funnel — once for surfacing it in autocomplete, and again for fetching its details? Vepler answers this with a sessionless, entity-keyed model:

The rule in one line

Discovery is free. Retrieval is charged once per address, per billing period. You never manage a session token — we deduplicate on the address itself, on the server.

​
Two ways to bill a search funnel

​
The session-token model

Some mapping and autocomplete APIs solve double-billing with a session token. Your client generates a token, attaches it to every autocomplete keystroke, and then attaches the same token to the final “fetch details” call. The provider bundles everything carrying that token into one billable session, so the keystrokes and the final fetch are billed together rather than separately. It works, but it pushes real responsibility onto your client:
  • You must generate, attach, and reset the token at exactly the right moments.
  • The token typically expires after a few minutes; get the lifecycle wrong and you are billed twice, or not at all.
  • It only deduplicates within one session — the same address fetched again tomorrow, or fetched through a different endpoint, is a brand-new charge.

​
The direct-access (sessionless) model — what Vepler uses

Vepler does not use session tokens. There is nothing for your client to generate, attach, or reset. Instead, billing is keyed on the address entity itself — its UPRN (Unique Property Reference Number), the stable identifier the rest of the API already uses as the locationId. When you retrieve an address, we record that this account has paid for this UPRN in this billing period. Any later retrieval of the same UPRN — same endpoint or different, one minute later or three weeks later — recognises that ledger entry and is not charged again until the next period.
This is why we call it direct access: you call the endpoint you need, directly, with no session bookkeeping. The deduplication happens server-side on data we control (the returned UPRN), not on a token your client has to manage correctly.

​
Why direct access is the better fit

We chose the entity-keyed model deliberately. The logic:

Nothing to get wrong

No token to generate, attach, expire, or reset. A category of integration bugs simply does not exist for you.

Deduplicates across the whole API

Autocomplete → /address/uprn → /property all collapse onto the same UPRN. A session token can only deduplicate within a single session; the address key spans endpoints and products.

Predictable invoices

You are billed for distinct addresses retrieved in a period, not for request volume. Retries, refreshes, and repeated lookups of an address you already paid for do not add to your bill.

Cache-friendly

Because the charge is tied to the address and the period — not to a short-lived session — you can cache a retrieved record for the rest of the period and re-fetch it freely if you need to.

​
How charging works

​
Discovery is free

Surfacing addresses so a user can pick one is not charged. Use autocomplete and postcode search as freely as your rate limits allow — typeahead that fires on every keystroke does not run up a bill. Discovery returns enough to identify and display a result — including its UPRN, which is the key you carry into the retrieval step. 
import { SDK } from '@vepler/sdk';

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

// Free: surface candidate addresses as the user types.
const suggestions = await vepler.search.suggest({ query: '10 Downing' });

// The user picks one; carry its UPRN into the (charged) retrieval step.
const chosenUprn = suggestions.results[0].uprn;

​
Retrieval is charged — once per address, per period

Fetching the full record for an address is the chargeable step. The first time you retrieve a given UPRN in a billing period, it is charged. Every subsequent retrieval of that same UPRN in the same period is recognised as already paid and costs nothing. 
// Charged the first time this UPRN is retrieved this period.
const first = await vepler.address.getByUprn({ uprn: chosenUprn });

// Same UPRN, same period — recognised as already paid, not charged again.
const again = await vepler.address.getByUprn({ uprn: chosenUprn });
The billing period is currently the calendar month (UTC). Retrieving an address you already paid for earlier in the same month is free; retrieving it again in a new month is a new charge.

​
A worked example

1

A user searches

They type “10 Downing Street” into your search box. Autocomplete fires several requests and surfaces matching addresses. Cost: nothing — discovery is free.
2

They select an address

You retrieve the full record for the chosen UPRN. Cost: one charge for that address.
3

They view it again later

The same user (or another user on your account) retrieves that UPRN again this month — from a detail page, a refresh, or a different endpoint. Cost: nothing — already paid this period.
4

Next month

The same address is retrieved again in a new billing period. Cost: one charge — a new period resets the ledger.
The funnel that surfaced the address and then fetched it is billed as one address, not as “autocomplete requests plus a details fetch”.

​
What this means for your integration

Don't build session logic

If you are porting from a session-token API, you can drop all token generation and lifecycle code. Call the endpoints directly.

Retries are safe

A retried retrieval after a timeout does not double-charge — the address is already claimed for the period. Retry with confidence.

Cache within the period

Store retrieved records and reuse them for the rest of the period. Re-fetching an address you have already paid for is free, so caching is an optimisation, not a billing necessity.

Bulk is one charge per address

Bulk and batch retrievals are billed per distinct address returned, deduplicated the same way as individual calls.

​
Free tiers and licensed access

Some accounts hold a licence grant that zero-rates address retrieval. Where that applies, retrieval is free for that account, but the model is otherwise identical — addresses are still recorded as retrieved, simply at no cost. There is nothing different to do in your integration.

​
Frequently asked questions

No. Discovery — autocomplete, typeahead, and postcode search — is free. You are only charged when you retrieve the full record for a specific address.
Once. The first retrieval in the billing period is charged; the other nine are recognised as already paid and cost nothing.
No. Billing is keyed on the address, not on the request. A retry re-claims the same address, sees it is already paid for the period, and is not charged again.
The UPRN. Two retrievals are deduplicated when they return the same UPRN, regardless of which endpoint surfaced or fetched it, or how the identifier was formatted.
At the start of the next billing period (currently the calendar month). The same address retrieved in a new period is a new charge.
No. There is no session token. Direct access means you call the endpoint you need with no session bookkeeping — deduplication is handled for you on the server.

​
Next steps

Usage & Limits

How requests are metered and how to optimise throughput.

Address API

Explore the address and search endpoints.