Address Verification API
Validate, correct, and parse addresses programmatically. 100 free lookups per month, then two cents per verification and half a cent per parse, and a 24-hour cache that makes repeat lookups free. Single calls or batches up to 100.
2¢
Per Verification
After 100 free lookups a month, billed monthly
100/mo
Free Tier
No credit card to start
24h
Cache (Free Hits)
Cached lookups do not count against your usage
100
Batch Size
Verify up to 100 addresses in one request
Benefits
Why Businesses Choose This Feature
- Drop-In Address Validation
POST a structured address and get back the standardized address, a deliverable flag, a residential flag when known, and messages for anything missing. Standard JSON. No SDK required.
- Parse Free-Text Addresses
POST /api/v1/addresses/parse takes a raw string like "123 main st apt 4b ny ny 10001" and returns clean structured fields. Great for ingesting messy CSV uploads or scraped data.
- 24h Cache, Cached Hits Free
Look up the same address twice in 24 hours and the second lookup is free — does not count against your quota or your billing. Great for forms with retry logic and re-validation flows.
- Batch Up to 100 Per Request
For bulk imports, send up to 100 addresses in one POST and get back 100 results. Each address counts as one verification. Pagination handled by your code if you need more.
- Per-Key Rate Limits & Usage
Create as many API keys as you need under Settings → API keys, one per app or environment, and revoke any key at any time. Every response carries X-RateLimit headers, and verify responses report how many free lookups remain this month.
- Google Address Validation, USPS-Checked in the US
Verifications run on Google Address Validation. US and Puerto Rico addresses are also checked against USPS delivery-point data, so deliverable means USPS confirmed the building and any unit number. The messages list says what could not be confirmed.
How the API Works
Generate an API Key
Sign up for a ShipWave account, open Settings → API keys, and create a ShipWave API key with Address verification checked. The key is shown once, so copy it then. Free tier gives you 100 verifications per month with no credit card required.
POST Your Address
Send a request to /api/v1/addresses/verify (single or batch) or /api/v1/addresses/parse with your API key in the Authorization header. Get back JSON.
Cache Handles Repeats
Identical addresses (same normalized key) within 24 hours return the cached result instantly and do not count against your quota. Saves you money on retry-heavy workflows.
API Reference Highlights
POST /api/v1/addresses/verify — Single or Batch
The verify endpoint accepts a structured address payload: { address: { street1, street2, city, state, zip, country } }. Country defaults to US if omitted. State and zip are required only for US and Puerto Rico addresses, so leave state out for countries that do not use one. The response includes the standardized address (USPS format with ZIP+4 for US addresses), a deliverable boolean, a residential flag when known, the list of fields that were corrected, and messages explaining anything missing or unconfirmed. For batch verification, POST { addresses: [...] } to /api/v1/addresses/verify-batch, up to 100 per request. Each batch entry counts as one verification against your quota. Cached lookups return immediately; new lookups usually take under a second. Failed lookups (invalid addresses) still count against quota.
POST /api/v1/addresses/parse — Free-Text to Structured
The parse endpoint takes messy real-world address strings and returns clean structured fields. Input: { raw: "123 Main St, Apt 4B, New York, NY 10001" }. Output: { street1: "123 Main St", street2: "Apt 4B", city: "New York", state: "NY", zip: "10001", country: "US", confidence: 0.95 }. Parsing is US-only today and works best with comma-separated input; confidence runs from 0 to 1, and below 0.6 means review the result. Parsing is cheaper than verification (0.5¢ vs 2¢) because it does not hit the underlying postal authority — it is pure NLP on the input string. Great for ingesting CSV uploads where users typed addresses into a single field, scraped data, or chat-based address collection. Pair it with verify for full validation: parse the string into components, then verify the components against USPS.
The 24-Hour Cache — Why Cached Hits Are Free
Every successful verification is cached for 24 hours under a normalized key (case-insensitive, surrounding whitespace ignored). If your application verifies the same address twice within the cache window, the second call returns the cached response instantly and does not increment your usage counter or your bill. This matters more than it sounds. Form retry logic, duplicate-detection workflows, and bulk re-imports often hit the same addresses repeatedly. Competitor APIs charge for every call regardless. ShipWave gives you the cache hit for free because it costs us nothing to serve a cached response — you should not pay for that.
Pricing Math vs. Competitors
ShipWave: 100 lookups free each month across verify and parse, then 2¢ per verification and 0.5¢ per parse, billed monthly to a card with no contract or monthly minimum. Repeat lookups of the same address within 24 hours are free. Shippo Addresses API: 6-9¢ per international lookup, US-only included in shipping subscription. Lob: 2-5¢ per US lookup, more for international. Smarty (formerly SmartyStreets): contract-based, typically $99/mo minimum for production use. The 100-free-per-month tier means small projects and side projects pay nothing, and there is no sales call: generate an API key, add a card when you outgrow the free tier, and keep going.
Authentication, Errors, and Status Codes
Authentication uses a Bearer token: Authorization: Bearer sw_live_… — create the key under Settings → API keys with Address verification checked. Successful verifications return 200 OK. Undeliverable addresses also return 200, with deliverable: false and messages explaining what is missing or unconfirmed; the lookup worked, the address just is not confirmed. Errors that prevent the lookup return 400 (malformed body, missing fields, or an unsupported country), 401 (missing, invalid, expired, or revoked key), 403 (the key does not have Address verification access), 429 (over 60 requests per minute per key), or 502 (the verification provider was unavailable; retry shortly). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
ShipWave Address API vs. Shippo, Lob, Smarty
| Feature | ShipWave | Shippo / Lob / Smarty |
|---|---|---|
| Price per US verify | 2¢ after 100 free | Lob 2-5¢, Smarty contract-based |
| Price per international verify | 2¢ flat | Shippo 6-9¢, Lob 4-10¢ |
| Free tier per month | 100 free, no card | Smarty 250 lifetime trial only |
| Cached hits free | Yes — 24h cache | No — every call billed |
| Batch size | 100 per request | Varies, often single-only |
| Free-text address parsing | Yes — 0.5¢ | Limited or paid add-on |
Who Uses the Address API
SaaS Apps Collecting Customer Data
Onboarding flows, shipping address fields, billing forms. Drop the API into your form validator and reject bad addresses at the source instead of failing at fulfillment.
Marketplaces & Multi-Tenant Platforms
If your platform handles fulfillment for thousands of sellers, batch verification keeps shipping costs predictable. The 24h cache absorbs repeat lookups of the same address from your account.
CSV Import & Data Cleanup
Inheriting a messy customer list? Parse the free-text strings, verify the structured components, and dump the cleaned data into your CRM. 100-per-batch makes this fast.
Frequently Asked Questions
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. Set the "country" field to a two-letter code; a country outside that list returns a 400 VALIDATION_ERROR instead of a guess.
What accuracy guarantees do you offer?
For US and Puerto Rico addresses, deliverable is true only when USPS delivery-point validation confirms the building and any unit number. Elsewhere it means Google matched a complete address to a specific building. Anything missing or unconfirmed is listed in messages so you can decide how strict to be. No verification service can guarantee a carrier will deliver.
What is the max batch size?
100 addresses per request. For larger imports, paginate client-side. Each address in a batch counts as one verification against your quota (cached hits within a batch are still free).
How does the cache hit ratio work?
Identical addresses (after normalization — case and whitespace) hit the cache for 24 hours. Every verify response includes cached: true or false and costCents, so you can monitor your effective cost per lookup.
Can I use test keys for development?
There are no separate test keys. Every key (sw_live_*) checks real addresses, so develop against a few real addresses and rely on the 24-hour cache for repeats. Never send made-up US addresses: the USPS data provider can cut off validation for repeated artificial addresses.
What happens if I exceed my quota?
The first 100 lookups each calendar month are free. To keep going, add a card in ShipWave under Settings → API Keys; after that verifications cost 2¢ and parses 0.5¢, billed monthly. Without a card, further lookups return HTTP 402 with a link to add one, until the next month. Every response includes freeTierRemaining so you can see where you stand.
Is there an SDK?
Not required — the API is standard JSON over HTTPS and works with curl, fetch, axios, requests, or any HTTP client. Send your key as a Bearer token in the Authorization header.
Explore More
Related Features
API Overview
The broader ShipWave API — labels, tracking, orders, and shipments in one platform.
Learn more →
Shipping Labels
Address verification is built into every label purchase, but the standalone API works for any use case.
Learn more →
Store Integrations
When you connect a store, addresses are auto-verified on import — no API calls needed.
Learn more →
Validate 100 Addresses a Month Free
Free tier gives you 100 verifications per month. No credit card to start. Generate an API key in 60 seconds.