API Documentation

Complete address validation APIs with industry-standard request/response formats.

US Street API

Full USPS CASS validation

US ZIP Code API

City/State/ZIP lookups

Autocomplete

Real-time suggestions

US Extract API

Parse text for addresses

Reverse Geocoding

Coords to addresses

Intl Street API

240+ countries

Intl Autocomplete

Global suggestions

Base URL

https://truaddress.net/api

SDK Libraries

Official SDKs for quick integration. Drop-in libraries with full TypeScript/type support.

Installation

🟨

JavaScript / TypeScript

npm install truaddress

BrowserNode.jsTypeScript

🐍

Python

pip install truaddress

Python 3.8+DjangoFlask

💎

Ruby / Rails

gem install truaddress

Ruby 2.7+RailsThread-safe

Quick Start

JavaScript / TypeScript

import TruAddress from 'truaddress';

const client = new TruAddress({ apiKey: 'YOUR_API_KEY' });

// Validate a US address
const results = await client.usStreet({
  street: '1600 Pennsylvania Ave NW',
  city: 'Washington',
  state: 'DC',
  zipcode: '20500'
});

if (results.length > 0 && TruAddress.isDeliverable(results[0])) {
  console.log('Valid:', results[0].delivery_line_1);
  console.log('DPV Code:', results[0].analysis.dpv_match_code);
}

Python

from truaddress import TruAddress

client = TruAddress(api_key="YOUR_API_KEY")

# Validate a US address
results = client.us_street(
    street="1600 Pennsylvania Ave NW",
    city="Washington",
    state="DC",
    zipcode="20500"
)

if results and TruAddress.is_deliverable(results[0]):
    print("Valid:", results[0]["delivery_line_1"])
    print("DPV Code:", results[0]["analysis"]["dpv_match_code"])

Ruby

require 'truaddress'

client = Truaddress::Client.new(api_key: "YOUR_API_KEY")

# Validate a US address
results = client.us_street(
  street: "1600 Pennsylvania Ave NW",
  city: "Washington",
  state: "DC",
  zipcode: "20500"
)

if results.any? && Truaddress::Client.deliverable?(results[0])
  puts "Valid: #{results[0]['delivery_line_1']}"
  puts "DPV Code: #{results[0]['analysis']['dpv_match_code']}"
end

Available Methods

Method	JavaScript	Python	Ruby
US Street	usStreet()	us_street()	us_street()
US ZIP Code	usZipCode()	us_zipcode()	us_zipcode()
US Autocomplete	usAutocomplete()	us_autocomplete()	us_autocomplete()
US Extract	usExtract()	us_extract()	us_extract()
US Reverse Geo	usReverseGeo()	us_reverse_geo()	us_reverse_geo()
Intl Street	intlStreet()	intl_street()	intl_street()
Intl Autocomplete	intlAutocomplete()	intl_autocomplete()	intl_autocomplete()
Validate	validate()	validate()	validate()
Correct	correct()	correct()	correct()
Autocomplete	autocomplete()	autocomplete()	autocomplete()

Helper Methods

All SDKs include helper methods for common validation checks:

isDeliverable(result)

Check if US address has DPV code "Y"

isCMRA(result)

Check if address is a mail drop (CMRA)

isVacant(result)

Check if US address is vacant

isVerified(result)

Check if international address is verified

formatUSAddress(result)

Get formatted US address string

formatIntlAddress(result)

Get formatted international address string

Framework Integration

Next.js / React

// app/api/validate/route.ts
import TruAddress from 'truaddress';

const client = new TruAddress({ apiKey: process.env.TRUADDRESS_API_KEY! });

export async function POST(request: Request) {
  const { street, city, state, zipcode } = await request.json();
  
  const results = await client.usStreet({ street, city, state, zipcode });
  const isValid = results.length > 0 && TruAddress.isDeliverable(results[0]);
  
  return Response.json({ valid: isValid, results });
}

Django

# views.py
from django.http import JsonResponse
from truaddress import TruAddress

client = TruAddress(api_key=settings.TRUADDRESS_API_KEY)

def validate_address(request):
    results = client.us_street(
        street=request.POST["street"],
        city=request.POST["city"],
        state=request.POST["state"],
        zipcode=request.POST["zipcode"]
    )
    is_valid = len(results) > 0 and TruAddress.is_deliverable(results[0])
    return JsonResponse({"valid": is_valid, "results": results})

Rails

# app/controllers/addresses_controller.rb
class AddressesController < ApplicationController
  def validate
    results = Truaddress.client.us_street(
      street: params[:street],
      city: params[:city],
      state: params[:state],
      zipcode: params[:zipcode]
    )
    is_valid = results.any? && Truaddress::Client.deliverable?(results.first)
    render json: { valid: is_valid, results: results }
  end
end

View full SDK documentation

Authentication

Authentication Required

All API requests require authentication. Unauthenticated requests will return a 401 error. Get your API key from the Dashboard.

Four authentication methods supported:

1. X-API-Key Header

Recommended

Best for server-side integrations where headers are easily configurable.

curl "https://truaddress.net/api/us-street?street=..." \
  -H "X-API-Key: tru_your_api_key_here"

2. Authorization Bearer Header

Standard OAuth-style bearer token authentication.

curl "https://truaddress.net/api/us-street?street=..." \
  -H "Authorization: Bearer tru_your_api_key_here"

3. Query Params (auth-token)

Use your TruAddress API key as the auth-token query parameter. The auth-id can be any identifier for your reference.

curl "https://truaddress.net/api/us-street?\
  auth-id=any-identifier&\
  auth-token=tru_your_api_key_here&\
  street=1600+Pennsylvania+Ave+NW"

4. Embedded Key Query Param

Embedded key style. Best for client-side apps with website key restrictions.

curl "https://truaddress.net/api/us-street?\
  key=tru_your_api_key_here&\
  street=1600+Pennsylvania+Ave+NW"

Migrating from another provider?

Use your TruAddress API key as the auth-token parameter. The auth-id parameter is accepted but only theauth-token is used for authentication. Our endpoints use industry-standard request/response formats for easy migration.

Validate API

POST/api/validate

Component-based international address validation. Returns industry-standard response format.

curl -X POST "https://truaddress.net/api/validate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tru_your_api_key" \
  -d '{
    "country": "US",
    "address1": "350 5th Avenue",
    "locality": "New York",
    "administrative_area": "NY",
    "postal_code": "10118"
  }'

Correct API

POST/api/correct

Freeform address standardization. Takes any address string and returns standardized components.

curl -X POST "https://truaddress.net/api/correct" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tru_your_api_key" \
  -d '{
    "freeform": "350 5th ave new york ny"
  }'

Autocomplete API

GET/api/autocomplete

Global address autocomplete. Returns suggestions as users type with coordinates and structured address data.

Query Parameters

Parameter	Type	Description
q	string	Search query (min 3 characters)
provider	string	Provider: google (default) or geoapify

Example Request

curl "https://truaddress.net/api/autocomplete?q=1600+penn" \
  -H "X-API-Key: tru_your_api_key"

US Street Address API

GET/POST/api/us-street

Validate and standardize US addresses with USPS CASS certification. Returns DPV codes, geocoding, and complete address metadata.

Input Fields

Field	Type	Description
street	string	Street address or freeform input (required)
city	string	City name
state	string	State name or abbreviation
zipcode	string	5 or 9 digit ZIP code
candidates	int	Max results (1-10, default 1)
match	string	strict \| invalid \| enhanced

Example Request

curl "https://truaddress.net/api/us-street?\
  street=1600+Pennsylvania+Ave+NW&\
  city=Washington&\
  state=DC&\
  zipcode=20500&\
  candidates=1" \
  -H "X-API-Key: tru_your_api_key"

Example Response

[{
  "input_index": 0,
  "candidate_index": 0,
  "delivery_line_1": "1600 Pennsylvania Ave NW",
  "last_line": "Washington DC 20500-0005",
  "delivery_point_barcode": "205000005992",
  "components": {
    "primary_number": "1600",
    "street_name": "Pennsylvania",
    "street_suffix": "Ave",
    "street_postdirection": "NW",
    "city_name": "Washington",
    "state_abbreviation": "DC",
    "zipcode": "20500",
    "plus4_code": "0005"
  },
  "metadata": {
    "record_type": "S",
    "zip_type": "Standard",
    "county_name": "District of Columbia",
    "latitude": 38.8976763,
    "longitude": -77.0365298,
    "precision": "Rooftop",
    "time_zone": "Eastern",
    "utc_offset": -5,
    "dst": true
  },
  "analysis": {
    "dpv_match_code": "Y",
    "dpv_footnotes": "AABB",
    "dpv_cmra": "N",
    "dpv_vacant": "N",
    "active": "Y"
  }
}]

US ZIP Code API

GET/POST/api/us-zipcode

Look up city/state information from ZIP codes, or find ZIP codes for a city/state combination.

Example Request

curl "https://truaddress.net/api/us-zipcode?zipcode=90210" \
  -H "X-API-Key: tru_your_api_key"

Example Response

[{
  "input_index": 0,
  "city_states": [{
    "city": "Beverly Hills",
    "state_abbreviation": "CA",
    "state": "California",
    "mailable_city": true
  }],
  "zipcodes": [{
    "zipcode": "90210",
    "zipcode_type": "S",
    "default_city": "Beverly Hills",
    "county_name": "Los Angeles",
    "state_abbreviation": "CA",
    "state": "California",
    "latitude": 34.0901,
    "longitude": -118.4065,
    "precision": "Zip5"
  }]
}]

US Autocomplete Pro API

GET/api/us-autocomplete

Get real-time address suggestions as users type. Supports filtering by state, city, and ZIP code.

Input Fields

Field	Description
search	Address text (max 32 chars, required)
max_results	Number of results (1-10, default 10)
include_only_states	Filter by states (e.g., CA;NY;TX)
prefer_geolocation	city \| none (default: city)

curl "https://truaddress.net/api/us-autocomplete?search=1600+Penn" \
  -H "X-API-Key: tru_your_api_key"

US Extract API

POST/api/us-extract

Extract and validate addresses from unstructured text or HTML. Returns position information for each found address.

curl -X POST "https://truaddress.net/api/us-extract" \
  -H "Content-Type: text/plain" \
  -H "X-API-Key: tru_your_api_key" \
  -d "Please ship to 1600 Pennsylvania Ave NW Washington DC 20500"

US Reverse Geocoding API

GET/api/us-reverse-geo

Find the closest street addresses to a given latitude/longitude coordinate.

curl "https://truaddress.net/api/us-reverse-geo?\
  latitude=40.748535&\
  longitude=-73.9856571" \
  -H "X-API-Key: tru_your_api_key"

International Street Address API

GET/api/intl-street

Validate addresses in 240+ countries. Supports freeform or component-based input with geocoding.

Example Request

curl "https://truaddress.net/api/intl-street?\
  country=BRA&\
  address1=Rua+Padre+Antonio+D'Angelo+121&\
  locality=Sao+Paulo&\
  administrative_area=SP&\
  postal_code=02516-040" \
  -H "X-API-Key: tru_your_api_key"

International Autocomplete API

GET/api/intl-autocomplete

Get address suggestions for 240+ countries. Uses V2 address_id pattern for detailed lookups.

curl "https://truaddress.net/api/intl-autocomplete?\
  country=CAN&\
  search=123+Main" \
  -H "X-API-Key: tru_your_api_key"

Error Handling

Status	Description
`200`	Success - returns array of candidates (empty [] if no match)
`400`	Bad request - malformed payload
`401`	Unauthorized - invalid API key
`413`	Request too large - max 100 addresses per batch
`422`	Unprocessable entity - missing required fields
`429`	Rate limit exceeded
`504`	Gateway timeout

Rate Limits

Free Tier

1,000

requests per month

Pro Tier

100,000

requests per month

Batch Limit

100

addresses per request

Ready to get started?

Try all endpoints in the playground or create your free account.

Try the Playground Create Free Account