TruAddress JavaScript/TypeScript SDK

Official JavaScript/TypeScript SDK for TruAddress - Address validation, autocomplete, and geocoding API.

Installation

npm install truaddress
# or
yarn add truaddress
# or
pnpm add truaddress

Quick Start

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 address:', results[0].delivery_line_1);
}

Available Methods

US Endpoints

usStreet(params) - US Street Address Validation

Validate and standardize US addresses with USPS data.

const results = await client.usStreet({
  street: '350 5th Avenue',
  city: 'New York',
  state: 'NY',
  zipcode: '10118'
});

console.log(results[0].analysis.dpv_match_code); // 'Y' = Deliverable
console.log(results[0].metadata.latitude);       // 40.748535

DPV Match Codes:

• Y - Confirmed deliverable
• S - Secondary (apt/suite) missing
• D - Secondary invalid
• N - Not deliverable

usZipCode(params) - ZIP Code Lookup

Look up city/state by ZIP or find ZIP codes by city/state.

// By ZIP code
const byZip = await client.usZipCode({ zipcode: '90210' });
console.log(byZip[0].city_states[0].city); // 'Beverly Hills'

// By city/state
const byCity = await client.usZipCode({ city: 'Austin', state: 'TX' });

usAutocomplete(params) - Address Autocomplete

Real-time address suggestions as users type.

const suggestions = await client.usAutocomplete({
  search: '350 5th Ave',
  max_results: 5,
  state_filter: ['NY']
});

suggestions.suggestions.forEach(s => {
  console.log(`${s.street_line}, ${s.city}, ${s.state} ${s.zipcode}`);
});

usExtract(text, options?) - Extract Addresses from Text

Find and validate addresses in unstructured text.

const result = await client.usExtract(
  'Ship to: 350 5th Avenue, New York, NY 10118. Thanks!'
);

console.log(result.meta.address_count);      // 1
console.log(result.addresses[0].verified);   // true

usReverseGeo(params) - Reverse Geocoding

Get addresses from GPS coordinates.

const nearby = await client.usReverseGeo({
  latitude: 40.748535,
  longitude: -73.9856571
});

nearby.results.forEach(r => {
  console.log(`${r.address.street} (${r.distance.toFixed(0)}m away)`);
});

International Endpoints

intlStreet(params) - International Address Validation

Validate addresses in 200+ countries.

const results = await client.intlStreet({
  country: 'GBR',
  freeform: '10 Downing Street, London'
});

console.log(results[0].components.postal_code); // 'SW1A 2AB'
console.log(TruAddress.isVerified(results[0])); // true

intlAutocomplete(params) - International Autocomplete

Address suggestions for international addresses.

const suggestions = await client.intlAutocomplete({
  search: 'Champs Elysees',
  country: 'FRA',
  max_results: 5
});

Core Endpoints

validate(params) - Global Address Validation

Unified validation for any country.

const results = await client.validate({
  country: 'US',
  address1: '350 5th Avenue',
  locality: 'New York',
  administrative_area: 'NY',
  postal_code: '10118'
});

correct(params) - Address Correction

Parse and correct freeform addresses.

const results = await client.correct({
  freeform: '1600 pennsylvania ave washington dc 20500'
});

console.log(results[0].address1); // 'Pennsylvania Avenue Northwest 1600'

autocomplete(params) - Global Autocomplete

Worldwide address suggestions.

const suggestions = await client.autocomplete({
  q: 'Buckingham Palace London',
  limit: 5
});

Helper Methods

// Check if US address is deliverable
TruAddress.isDeliverable(result)  // DPV code = 'Y'

// Check if US address is a mail drop (CMRA)
TruAddress.isCMRA(result)

// Check if US address is vacant
TruAddress.isVacant(result)

// Check if international address is verified
TruAddress.isVerified(result)

// Format addresses as strings
TruAddress.formatUSAddress(result)   // "350 5th Ave, New York NY 10118"
TruAddress.formatIntlAddress(result) // "10 Downing Street, London, SW1A 2AB"

Configuration

const client = new TruAddress({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://truaddress.net'  // Optional: custom base URL
});

TypeScript Support

Full TypeScript support with exported types:

import TruAddress, { 
  USStreetResult, 
  USStreetRequest,
  IntlStreetResult,
  ValidateRequest 
} from 'truaddress';

Error Handling

try {
  const results = await client.usStreet({ street: '123 Main St' });
} catch (error) {
  console.error('Validation failed:', error.message);
}

Browser & Node.js

Works in both environments. Uses native fetch (Node.js 18+ or browser).

License

MIT