Locations API

The Flash Americas Locations API provides ZIP code lookup, city search, and address validation capabilities to support shipping address autocomplete and validation. These endpoints use the same API key authentication as quote requests.

Overview

The Locations API provides:

ZIP/Postal Code Search with autocomplete support
City Name Search across multiple countries
Address Validation and correction
Geocoding with latitude/longitude coordinates
Multi-Country Support for US, Mexico, and Canada

Endpoints

Method	Endpoint	Description
GET	`/location/search/{location}`	Search locations by ZIP code or city name
GET	`/location/search/{country}/{location}`	Search locations within specific country
POST	`/address/validate`	Validate and correct shipping addresses

Location Search (All Countries)

Search for locations by ZIP code or city name across all supported countries.

Request

GET /location/search/{location}http

GET https://ship.flashamericas.com/api/v1/location/search/75201
Authorization: Bearer YOUR_API_KEY
Accept: application/json

URL Parameters

Parameter	Type	Description
`location`	string	ZIP code (numeric) or city name (text)

Examples

ZIP code searchbash

# Search by ZIP code
curl -X GET "https://ship.flashamericas.com/api/v1/location/search/75201" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

# City name search
curl -X GET "https://ship.flashamericas.com/api/v1/location/search/DALLAS" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

# ZIP prefix autocomplete
curl -X GET "https://ship.flashamericas.com/api/v1/location/search/752" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

Response

Location search responsejson

{
"success": true,
"data": [
  {
    "zip": "75201",
    "city": "DALLAS",
    "state": "TX",
    "full_state": "Texas",
    "country": "US",
    "county": "Dallas",
    "lat": 32.7767,
    "lng": -96.7970
  }
],
"total": 1,
"search_type": "zip"
}

Location Search by Country

Search for locations within a specific country to improve search accuracy and performance.

Request

GET /location/search/{country}/{location}http

GET https://ship.flashamericas.com/api/v1/location/search/US/MIAMI
Authorization: Bearer YOUR_API_KEY
Accept: application/json

URL Parameters

Parameter	Type	Description
`country`	string	Country code (US, MX, CA)
`location`	string	ZIP code or city name

Supported Countries

Country	Code	Description
United States	US	ZIP codes and cities
Mexico	MX	Postal codes and cities
Canada	CA	Postal codes and cities

Examples

Country-specific searchesbash

# US ZIP code search
curl -X GET "https://ship.flashamericas.com/api/v1/location/search/US/75201" \
-H "Authorization: Bearer YOUR_API_KEY"

# Mexico city search
curl -X GET "https://ship.flashamericas.com/api/v1/location/search/MX/GUADALAJARA" \
-H "Authorization: Bearer YOUR_API_KEY"

# Canada postal code search
curl -X GET "https://ship.flashamericas.com/api/v1/location/search/CA/H3A" \
-H "Authorization: Bearer YOUR_API_KEY"

Address Validation

Validate and correct shipping addresses using the TMS address validation service.

Request

POST /address/validatehttp

POST https://ship.flashamericas.com/api/v1/address/validate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Request Body

Address validation requestjson

{
"street1": "1600 Pennsylvania Avenue NW",
"street2": "",
"city": "Washington", 
"state": "DC",
"zip": "20500",
"country": "US"
}

Response

Address validation responsejson

{
"success": true,
"validation_status": "VALIDATED_CHANGED",
"original_address": {
  "street1": "1600 Pennsylvania Avenue NW",
  "street2": "",
  "city": "Washington",
  "state": "DC",
  "zip": "20500",
  "country": "US"
},
"validated_address": {
  "street1": "1600 Pennsylvania Avenue NW",
  "street2": "",
  "city": "Washington",
  "state": "DC", 
  "zip": "20500-0001",
  "country": "US"
},
"requires_correction": true
}

Search Patterns

The API automatically detects different input patterns and provides appropriate results.

ZIP/Postal Code Search

Pattern Recognition:

Numeric values: 75201, 78701, 90210
Canadian postal codes: H3A1A1, M5H2N2
Mexican postal codes: 09300, 88000

Behavior:

Exact matches return specific location details
Partial matches (3+ digits) return autocomplete suggestions
Results limited to 50 locations for partial matches

City Name Search

Pattern Recognition:

Text values: DALLAS, MIAMI, GUADALAJARA
Case insensitive: dallas, Miami, GuAdAlAjArA

Behavior:

Finds cities starting with the search term
Returns multiple matches if cities exist in different states
Includes state/province and country for disambiguation

Integration Examples

ZIP Code Autocomplete

ZIP code autocomplete componentjavascript

async function zipCodeAutocomplete(zipPrefix) {
if (zipPrefix.length < 3) return [];

const response = await fetch(
  `https://ship.flashamericas.com/api/v1/location/search/${zipPrefix}`,
  {
    headers: {
      'Authorization': 'Bearer your-api-key',
      'Accept': 'application/json'
    }
  }
);

const data = await response.json();

return data.data.map(location => ({
  value: location.zip,
  label: `${location.zip} - ${location.city}, ${location.state}`,
  city: location.city,
  state: location.state,
  country: location.country,
  coordinates: [location.lat, location.lng]
}));
}

// Usage in form
document.getElementById('zipInput').addEventListener('input', async (e) => {
const value = e.target.value;
if (value.length >= 3) {
  const suggestions = await zipCodeAutocomplete(value);
  displaySuggestions(suggestions);
}
});

Address Form Auto-Population

Auto-populate address fieldsjavascript

async function autoPopulateFromZip(zipCode) {
try {
  const response = await fetch(
    `https://ship.flashamericas.com/api/v1/location/search/${zipCode}`,
    {
      headers: {
        'Authorization': 'Bearer your-api-key',
        'Accept': 'application/json'
      }
    }
  );
  
  const data = await response.json();
  
  if (data.data.length > 0) {
    const location = data.data[0];
    
    // Auto-populate form fields
    document.getElementById('cityInput').value = location.city;
    document.getElementById('stateInput').value = location.state;
    document.getElementById('countryInput').value = location.country;
    
    return location;
  }
  
  return null;
} catch (error) {
  console.error('Failed to auto-populate address:', error);
  return null;
}
}

// Usage
document.getElementById('zipInput').addEventListener('blur', async (e) => {
const zipCode = e.target.value.trim();
if (zipCode.length >= 5) {
  await autoPopulateFromZip(zipCode);
}
});

City Search with Country Filter

City search with filteringjavascript

async function citySearch(cityName, country = null) {
const endpoint = country 
  ? `/location/search/${country}/${cityName}`
  : `/location/search/${cityName}`;
  
const response = await fetch(
  `https://ship.flashamericas.com/api/v1${endpoint}`,
  {
    headers: {
      'Authorization': 'Bearer your-api-key',
      'Accept': 'application/json'
    }
  }
);

const data = await response.json();

return data.data.map(location => ({
  value: `${location.city}, ${location.state}`,
  zip: location.zip,
  city: location.city,
  state: location.state,
  country: location.country,
  fullAddress: `${location.city}, ${location.state} ${location.zip}, ${location.country}`
}));
}

// Usage examples
const usCities = await citySearch('MIAMI', 'US');
const mexicoCities = await citySearch('GUADALAJARA', 'MX');
const allCities = await citySearch('PARIS'); // All countries

Cross-Border Validation

Validate cross-border addressesjavascript

async function validateCrossBorderAddresses(originAddress, destinationAddress) {
const results = {
  origin: null,
  destination: null,
  errors: []
};

try {
  // Validate origin address
  const originResponse = await fetch(
    'https://ship.flashamericas.com/api/v1/address/validate',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your-api-key',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify(originAddress)
    }
  );
  
  if (originResponse.ok) {
    results.origin = await originResponse.json();
  }
  
  // Validate destination address
  const destResponse = await fetch(
    'https://ship.flashamericas.com/api/v1/address/validate',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your-api-key',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify(destinationAddress)
    }
  );
  
  if (destResponse.ok) {
    results.destination = await destResponse.json();
  }
  
} catch (error) {
  results.errors.push(`Validation failed: ${error.message}`);
}

return results;
}

// Usage for cross-border shipment
const addresses = await validateCrossBorderAddresses(
{
  street1: "123 Main St",
  city: "Laredo",
  state: "TX",
  zip: "78040",
  country: "US"
},
{
  street1: "Av. Principal 456",
  city: "Nuevo Laredo",
  state: "TAM", 
  zip: "88000",
  country: "MX"
}
);

Error Handling

Common Errors

Invalid country codejson

{
"success": false,
"error": "Invalid country code. Allowed values: US, MX, CA"
}

No results foundjson

{
"success": true,
"data": [],
"total": 0,
"search_type": "zip"
}

Address validation unavailablejson

{
"success": false,
"error": "Address validation service unavailable",
"status_code": 503
}

Best Practices

Debounce search requests to avoid excessive API calls
Cache common lookups to improve performance
Handle empty results gracefully
Validate input before making requests
Use country-specific endpoints when possible

Debounced search implementationjavascript

const debounce = (func, delay) => {
let timeoutId;
return (...args) => {
  clearTimeout(timeoutId);
  timeoutId = setTimeout(() => func.apply(null, args), delay);
};
};

// Debounced location search
const debouncedLocationSearch = debounce(async (query) => {
if (query.length >= 3) {
  const results = await locationSearch(query);
  updateSuggestions(results);
}
}, 300);

// Use with input events
document.getElementById('locationInput').addEventListener('input', (e) => {
debouncedLocationSearch(e.target.value);
});

Rate Limiting

Limit: 60 requests per minute per API key
Recommendation: Implement debouncing with 300ms delay
Best Practice: Cache frequent lookups locally

Use Cases

1. Shipping Address Forms

Auto-populate city/state from ZIP code entry
Provide ZIP code suggestions as user types
Validate addresses before quote requests

2. Cross-Border Shipping

Validate US and Mexico addresses
Find border crossing locations
Support multi-country operations

3. Location-Based Services

Store locators with shipping cost integration
Service area validation
Geographic routing optimization

4. Data Quality

Clean and standardize address databases
Validate bulk address imports
Improve delivery success rates

Data Coverage

United States: 40,000+ ZIP codes with full address data
Mexico: 30,000+ postal codes with city/state information
Canada: 850,000+ postal codes with province details
Accuracy: Based on official postal service databases
Updates: Regular synchronization with postal authorities

Next Steps

Quotes API - Use validated addresses for accurate quotes
SAT Codes API - Add Mexican tax codes for cross-border shipping
Integration Examples - See complete address validation workflows

Locations API

Overview

Endpoints

Location Search (All Countries)

Request

URL Parameters

Examples

Response

Location Search by Country

Request

URL Parameters

Supported Countries

Examples

Address Validation

Request

Request Body

Response

Search Patterns

ZIP/Postal Code Search

City Name Search

Integration Examples

ZIP Code Autocomplete

Address Form Auto-Population

City Search with Country Filter

Cross-Border Validation

Error Handling

Common Errors

Best Practices

Rate Limiting

Use Cases

1. Shipping Address Forms

2. Cross-Border Shipping

3. Location-Based Services

4. Data Quality

Data Coverage

Next Steps

On this page