Retrieves city information and geographic identifiers (including postal codes) based on city name, state, and country. Use this endpoint when postal codes are unavailable or to validate and normalize city names for address forms.

When to use this endpoint:

Validate city names when postal codes are not provided by users
Retrieve postal codes for a known city and state combination
Normalize city name variations (e.g., "New York" vs "NYC" vs "New York City")
Auto-complete city suggestions in address forms

Data Quality Expectations

Matching: City names are matched using fuzzy matching to handle variations and abbreviations
Normalization: City names are returned in standardized format required by carriers
Completeness: Response includes city name, state, country, and associated postal codes when available

Edge Cases

Multiple matches: When a city name matches multiple cities (e.g., "Springfield" exists in many US states), the response includes all matches. Filter by state when possible.
Name variations: City names with common variations (abbreviations, accents, alternative spellings) may return multiple results. Use the most specific match.
Missing state: Some countries don't use states/provinces. Provide country code and city name only in these cases.
No matches: If no city matches are found, verify the spelling and try alternative name variations.

Localization Notes

City name formats: Some countries use different city name conventions (e.g., district names in some regions)
State requirements: State/province is required for countries that use them (US, Mexico, Canada, etc.)
Language variations: City names may vary by language (e.g., "México" vs "Mexico City")

Notes

Sometimes cities have multiple zip codes—this endpoint returns all available zip codes for the given city
Use this endpoint when postal codes are not available or to validate city names
Results help ensure address accuracy before creating shipments