Address autocomplete, normalization and tax lookup API
Search, autocomplete and clean addresses worldwide, with a sales-tax profile, from an offline corpus.
What it does
- The Address Intelligence API finds, completes and tidies addresses from a corpus Takelan holds itself. You send a free-text address or a few fields. You get ranked candidates with parsed parts, coordinates, country reference data and, if you ask, the sales, VAT or GST rate that applies there.
- It solves a common product problem: forms full of typos, half-filled addresses and wrong tax rates. Because the data is offline, there is no per-call fee to a third-party address vendor, and your users' typing is not sent to one.
- Be clear about scope. This is address search, autocomplete and normalization over public datasets (GeoNames, OpenAddresses, US TIGER ranges, published sales-tax and VAT tables). It is not postal-carrier or delivery-point validation. Tax rates are indicative: the response itself says to confirm with a tax authority before invoicing.
- Affordable by design. Start free* within platform limits for connected ShadowCradle organizations, with affordable pricing beyond that. *Free within platform limits; usage beyond limits may be charged to maintain the platform.
See how it works
From a messy address to a structured one
Example use cases
Smarter checkout and signup forms
Product teams call /autocomplete as people type, then /normalize on submit to fill city, region and postal code and flag fields that are missing or invalid.
Tax-aware quotes for MSP billing
An MSP quoting a new client in another state posts the location to /tax and gets the billing rate with a state, county and city breakdown to put on the estimate.
Clean up a messy customer list
Ops teams run old CRM exports through /normalize to get one canonical, country-correct format per record before a mailing or migration.
Country and region pick-lists
Build dropdowns from /countries, /countries/{iso2}/regions and /counties, with postal-code formats and phone prefixes included.
Place lookup for support and field work
Support tools resolve a customer-typed location to coordinates and time zone to route a call or schedule a visit.
Try it
Search an address with tax
curl -s "https://app.takelan.com/api/v1/addresses/search?q=11613+Colony+Lake+Dr&country=US&include_tax=true" \ -H "X-API-Key: $TAKELAN_API_KEY"
Response (trimmed, fictional): { "query": "11613 Colony Lake Dr", "total_results": 1, "best_match": { "score": 0.94, "match_type": "street", "formatted": "11613 Colony Lake Dr, Example City, FL 33000, United States", "tax": { "billing_rate_percent": 7.0, "confidence": "exact", "coverage": "local_jurisdictions" } }, "cached": false }
Tax profile for a location
curl -s -X POST "https://app.takelan.com/api/v1/addresses/tax" \
-H "X-API-Key: $TAKELAN_API_KEY" -H "Content-Type: application/json" \
-d '{"country":"US","region":"FL","city":"Example City","postal_code":"33000"}'Returns 404 when there is no tax data for that location.
Endpoints
POST /api/v1/addresses/searchSearch: ranked candidates for a free-text address, with optional tax and country info.GET /api/v1/addresses/searchSearch: same, as a query string (q, country, postal_code, limit up to 100, include_tax).GET /api/v1/addresses/autocompleteSearch: typeahead suggestions (limit up to 25).POST /api/v1/addresses/normalizeClean: canonical parts, country-correct lines, per-field verdict (ok, corrected, missing, invalid).POST /api/v1/addresses/taxTax: billing rate and breakdown, plus effective property tax where known.GET /api/v1/addresses/{address_id}Search: fetch one candidate by id.GET /api/v1/addresses/countriesReference: list countries.GET /api/v1/addresses/countries/{iso2}Reference: one country (currency, phone prefix, postal format, languages).GET /api/v1/addresses/countries/{iso2}/regionsReference: states or provinces.GET /api/v1/addresses/countries/{iso2}/countiesReference: counties or districts.GET /api/v1/addresses/statsCorpus: size and coverage.GET /api/v1/addresses/usageCorpus: your recent usage.GET /api/v1/addresses/datasetsCorpus: dataset status. Refresh and update calls are admin operations.
MCP
Available as tools through /mcp/utils. Read tools work by default with an API key. Anything that writes is off until your tenant turns on the writes switch, and a read-only key never writes. Calls run with your own permissions. About MCP
Common questions
Is there an address autocomplete API without per-call fees?
Yes. Takelan serves addresses from its own offline corpus, so there is no third-party per-call charge on the lookup itself. Affordable pricing applies beyond platform limits.
Does this validate addresses to postal standards?
No. It searches and normalizes using public datasets and gives a per-field verdict. It does not confirm that a carrier can deliver to the address.
How do I get the sales tax rate for an address by API?
POST the country, region, city and postal code to /api/v1/addresses/tax, or set include_tax on a search. You get a billing rate, a breakdown and a coverage flag.
How accurate are the tax rates?
They come from published tables and are indicative. The response carries a disclaimer to confirm with a tax authority before invoicing. The coverage field says whether local rates were resolved.
Can I normalize a messy address string?
Yes. Send fields or a raw line to /normalize. You get canonical parts and a verdict for each field.
Which countries are covered?
Reference data is worldwide. Street-level depth varies by country, and each search response includes notes about coverage limits for that result.
How do I authenticate to the address API?
Send your key in the X-API-Key header, or a bearer token. Tenant is taken from the key, never from the request body.
Can an AI agent look up addresses?
Yes, through the Utils MCP endpoint. Reads work by default. Writes need a tenant switch.