TruAddress

https://truaddress.net/docs
Admin
TruAddress is a comprehensive address validation API platform offering USPS-certified US address...
Tokens:4,525
Snippets:31
Trust Score:2.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install TruAddress SDK

Source: https://truaddress.net/docs

Commands to install the official TruAddress library for various programming environments.

```bash
npm install truaddress
```

```bash
pip install truaddress
```

```bash
gem install truaddress
```

--------------------------------

### Autocomplete API Request

Source: https://truaddress.net/docs

Example of using the Autocomplete API to get global address suggestions based on a query string. Requires a 'q' parameter (min 3 characters) and an X-API-Key header. The 'provider' parameter can specify 'google' or 'geoapify'.

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

--------------------------------

### Integrate Address Validation in Web Frameworks

Source: https://truaddress.net/docs

Examples of implementing address validation endpoints within Next.js, Django, and Ruby on Rails applications.

```typescript
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 });
}
```

```python
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})
```

```ruby
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
```

--------------------------------

### GET /api/autocomplete

Source: https://truaddress.net/docs

Provides global address suggestions as users type.

```APIDOC
## GET /api/autocomplete

### Description
Returns address suggestions based on a partial input string.

### Method
GET

### Endpoint
/api/autocomplete

### Query Parameters
- **q** (string) - Required - Search query (min 3 chars)
- **provider** (string) - Optional - Provider: google (default) or geoapify

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

--------------------------------

### US ZIP Code API Request

Source: https://truaddress.net/docs

Example for the US ZIP Code API, which allows looking up city/state information from ZIP codes or finding ZIP codes for a city/state. It requires a 'zipcode' parameter and an X-API-Key header.

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

--------------------------------

### International Autocomplete API - Get Global Address Suggestions

Source: https://truaddress.net/docs

Provides address suggestions for over 240 countries using the V2 address_id pattern for detailed lookups. Requires country code, search query, and an API key.

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

--------------------------------

### International Autocomplete API

Source: https://truaddress.net/docs

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

```APIDOC
## International Autocomplete API

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

### Method
GET

### Endpoint
/api/intl-autocomplete

### Parameters
#### Query Parameters
- **country** (string) - Required - ISO 3166-1 alpha-3 country code (e.g., CAN, USA).
- **search** (string) - Required - The address text to search for.

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

### Response
#### Success Response (200)
- **candidates** (array) - Array of address suggestion objects.

#### Response Example
```json
{
  "candidates": [
    {
      "address_id": "some_address_id",
      "text": "123 Main Street, Anytown, ON, M1M 1M1"
    }
  ]
}
```
```

--------------------------------

### Validate API Request

Source: https://truaddress.net/docs

Example of how to use the Validate API endpoint to perform component-based international address validation. It requires a JSON payload with address components and an X-API-Key header for authentication.

```bash
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"
  }'
```

--------------------------------

### US Autocomplete API - Get Address Suggestions

Source: https://truaddress.net/docs

Fetches real-time address suggestions as users type. Supports filtering by state, city, and ZIP code. Requires a search query and an API key.

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

--------------------------------

### US Autocomplete Pro API

Source: https://truaddress.net/docs

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

```APIDOC
## US Autocomplete Pro API

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

### Method
GET

### Endpoint
/api/us-autocomplete

### Parameters
#### Query Parameters
- **search** (string) - Required - Address text (max 32 chars)
- **max_results** (integer) - Optional - Number of results (1-10, default 10)
- **include_only_states** (string) - Optional - Filter by states (e.g., CA;NY;TX)
- **prefer_geolocation** (string) - Optional - 'city' or 'none' (default: city)

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

### Response
#### Success Response (200)
- **candidates** (array) - Array of address suggestion objects.

#### Response Example
```json
{
  "candidates": [
    {
      "street": "1600 Pennsylvania Ave NW",
      "city": "Washington",
      "state": "DC",
      "zip": "20500"
    }
  ]
}
```
```

--------------------------------

### US Street Address API Request

Source: https://truaddress.net/docs

Shows how to validate and standardize US addresses using the US Street Address API. This endpoint accepts GET or POST requests with parameters like street, city, state, zipcode, and requires an X-API-Key header.

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

--------------------------------

### Validate US Address with SDK

Source: https://truaddress.net/docs

Demonstrates how to initialize the client and perform a US street address validation request.

```javascript
import TruAddress from 'truaddress';

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

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);
}
```

```python
from truaddress import TruAddress

client = TruAddress(api_key="YOUR_API_KEY")

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"])
```

```ruby
require 'truaddress'

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

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']}"
end
```

--------------------------------

### POST /api/correct

Source: https://truaddress.net/docs

Standardizes freeform address strings into structured components.

```APIDOC
## POST /api/correct

### Description
Standardizes a freeform address string into structured components.

### Method
POST

### Endpoint
/api/correct

### Request Body
- **freeform** (string) - Required - The raw address string to standardize

### Request Example
{
  "freeform": "350 5th ave new york ny"
}
```

--------------------------------

### API Authentication Methods

Source: https://truaddress.net/docs

Demonstrates four different methods for authenticating API requests: X-API-Key Header, Authorization Bearer Header, Query Params (auth-token), and Embedded Key Query Param. All methods require a TruAddress API key.

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

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

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

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

--------------------------------

### Correct API Request

Source: https://truaddress.net/docs

Demonstrates how to use the Correct API endpoint for freeform address standardization. It accepts a JSON payload with a 'freeform' address string and requires an X-API-Key header.

```bash
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"
  }'
```

--------------------------------

### GET/POST /api/us-zipcode

Source: https://truaddress.net/docs

Look up city/state information from ZIP codes or vice versa.

```APIDOC
## GET/POST /api/us-zipcode

### Description
Retrieves city and state information for a given ZIP code.

### Method
GET/POST

### Endpoint
/api/us-zipcode

### Query Parameters
- **zipcode** (string) - Required - The 5-digit ZIP code

### Response Example
[{
  "city_states": [{
    "city": "Beverly Hills",
    "state": "California"
  }]
}]
```

--------------------------------

### US Reverse Geocoding API - Find Addresses by Coordinates

Source: https://truaddress.net/docs

Finds the closest street addresses to a given latitude and longitude coordinate. Requires latitude, longitude, and an API key.

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

--------------------------------

### POST /api/validate

Source: https://truaddress.net/docs

Performs component-based international address validation.

```APIDOC
## POST /api/validate

### Description
Validates international addresses using component-based inputs.

### Method
POST

### Endpoint
/api/validate

### Request Body
- **country** (string) - Required - ISO country code
- **address1** (string) - Required - Address line 1
- **locality** (string) - Optional - City or locality
- **administrative_area** (string) - Optional - State or province
- **postal_code** (string) - Optional - Postal code

### Request Example
{
  "country": "US",
  "address1": "350 5th Avenue",
  "locality": "New York",
  "administrative_area": "NY",
  "postal_code": "10118"
}
```

--------------------------------

### GET/POST /api/us-street

Source: https://truaddress.net/docs

Validates and standardizes US addresses with USPS CASS certification.

```APIDOC
## GET/POST /api/us-street

### Description
Validates US addresses and returns DPV codes, geocoding, and metadata.

### Method
GET/POST

### Endpoint
/api/us-street

### Query Parameters
- **street** (string) - Required - Street address
- **city** (string) - Optional - City name
- **state** (string) - Optional - State abbreviation
- **zipcode** (string) - Optional - ZIP code
- **candidates** (int) - Optional - Max results

### Response Example
[{
  "delivery_line_1": "1600 Pennsylvania Ave NW",
  "components": {
    "city_name": "Washington",
    "state_abbreviation": "DC"
  },
  "metadata": {
    "latitude": 38.8976763,
    "longitude": -77.0365298
  }
}]
```

--------------------------------

### US Extract API - Extract Addresses from Text

Source: https://truaddress.net/docs

Extracts and validates addresses from unstructured text or HTML. Returns position information for each found address. Requires a POST request with plain text content and an API key.

```bash
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 Extract API

Source: https://truaddress.net/docs

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

```APIDOC
## US Extract API

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

### Method
POST

### Endpoint
/api/us-extract

### Parameters
#### Request Body
- **text** (string) - Required - Unstructured text or HTML containing the address.

### Request Example
```bash
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"
```

### Response
#### Success Response (200)
- **addresses** (array) - Array of extracted and validated address objects.

#### Response Example
```json
{
  "addresses": [
    {
      "street": "1600 Pennsylvania Ave NW",
      "city": "Washington",
      "state": "DC",
      "zip": "20500",
      "position": {
        "start": 15,
        "end": 59
      }
    }
  ]
}
```
```

--------------------------------

### International Street Address API - Validate Global Addresses

Source: https://truaddress.net/docs

Validates addresses in over 240 countries. Supports freeform or component-based input with geocoding. Requires country code, address components, and an API key.

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

--------------------------------

### US Reverse Geocoding API

Source: https://truaddress.net/docs

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

```APIDOC
## US Reverse Geocoding API

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

### Method
GET

### Endpoint
/api/us-reverse-geo

### Parameters
#### Query Parameters
- **latitude** (number) - Required - The latitude coordinate.
- **longitude** (number) - Required - The longitude coordinate.

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

### Response
#### Success Response (200)
- **address** (object) - The closest street address object.

#### Response Example
```json
{
  "address": {
    "street": "Empire State Building",
    "city": "New York",
    "state": "NY",
    "zip": "10001"
  }
}
```
```

--------------------------------

### International Street Address API

Source: https://truaddress.net/docs

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

```APIDOC
## International Street Address API

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

### Method
GET

### Endpoint
/api/intl-street

### Parameters
#### Query Parameters
- **country** (string) - Required - ISO 3166-1 alpha-3 country code (e.g., BRA, CAN, USA).
- **address1** (string) - Optional - The primary address line.
- **locality** (string) - Optional - The city or locality.
- **administrative_area** (string) - Optional - The state, province, or region.
- **postal_code** (string) - Optional - The postal code.

### Request Example
```bash
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"
```

### Response
#### Success Response (200)
- **address** (object) - The validated international address object.

#### Response Example
```json
{
  "address": {
    "country": "BRA",
    "address1": "Rua Padre Antonio D'Angelo, 121",
    "locality": "São Paulo",
    "administrative_area": "SP",
    "postal_code": "02516-040"
  }
}
```
```
Tokens:
Raw