Developers & API

Address verification API

A standalone API for verifying, batch-verifying, and parsing addresses, with metered billing and a generous free tier.

Three endpoints

POST /api/v1/addresses/verify — verify a single address with Google Address Validation. US and Puerto Rico addresses are also checked against USPS data and come back in USPS format with ZIP+4.
POST /api/v1/addresses/verify-batch — verify up to 100 addresses in one call. Returns one result per address, in input order, each with its own ok flag.
POST /api/v1/addresses/parse — split a US address string such as { "raw": "123 Main St, Apt 4B, New York, NY 10001" } into structured fields with a 0–1 confidence score.

Authentication

API calls require a Bearer token in the Authorization header. Generate a token at Admin → Settings → API Keys. Check Address verification when you create it (scope addresses:verify). The key is shown once, so copy it then. Keys with only Shipping API access get a 403.

Metered billing

Pricing:

Free tier: the first 100 new lookups each calendar month, across verify, batch verify, and parse. No card needed.
Verify: $0.02 per address after the free tier.
Batch verify: same per-address price; a batch of 50 counts as 50 lookups.
Parse: $0.005 per call after the free tier.

To go past the free tier, add a card under Settings → API Keys; usage is billed monthly through Stripe. Without a card, lookups past the free tier return HTTP 402 until the next month. Cache hits (see below) never count.

24-hour cache

Every verified address is cached for 24 hours keyed on the normalized address fields. If you verify the same address twice in 24 hours, the second call is served from cache, returns instantly, and isn't billed. This dramatically reduces cost for workloads with repeated addresses (e.g. checkout abandonment recovery where you might verify the same address 3+ times).

Response format

A verification response includes the standardized address (street1, street2, city, state, zip, country), a deliverable flag, a residential flag when known, correctedFields listing which fields changed, and messages explaining anything missing or unconfirmed (for example a missing apartment or suite number). deliverable is true only when the address is complete and matched to a specific building; for US addresses USPS must also confirm the building and any unit. Most users allow deliverable addresses through automatically and ask the customer to confirm the rest.

FAQs

Which countries are supported?

The 40 countries and regions Google Address Validation covers, including the US, Puerto Rico, Canada, Mexico, the UK, Australia, New Zealand, Japan, and most of Europe. Other countries return a 400 error.

Is there a rate limit?

Yes—60 requests per minute per API key. A batch counts as one request, so use verify-batch for high throughput.

What happens to my data?

Each address is sent to Google Address Validation to be checked. ShipWave keeps a record of each lookup with your account so repeat lookups within 24 hours are served from cache and your monthly usage can be counted.

How is the verification API different from order address validation?

The API gives you direct access without creating an order—useful for checkout-time validation, list cleaning, or any non-shipping use case. It uses Google Address Validation; label rating uses a separate address check.

Back to Help Center