AgentSkillsCN

zip-code-to-lat-and-long

利用免费 API 将美国邮政编码转换为经纬度坐标,无需 API 密钥。支持 Zippopotam.us(最简单)与 OpenStreetMap Nominatim(备选方案),并附带 curl 示例。

SKILL.md
--- frontmatter
name: zip-code-to-lat-and-long
description: Convert US zip codes to latitude/longitude coordinates using free APIs. No API key required. Covers Zippopotam.us (simplest) and OpenStreetMap Nominatim (alternative) with curl examples.

Zip Code to Latitude/Longitude APIs

Two free options for converting US zip codes to coordinates, no API key required.

Option 1: Zippopotam.us (Recommended)

The simplest option - purpose-built for zip code lookups. No authentication, no rate limits documented, CORS enabled.

Base URL

code
https://api.zippopotam.us

Endpoint Format

code
GET /us/{zip_code}

Example CURL

bash
curl "https://api.zippopotam.us/us/90210"

Response Format

json
{
  "post code": "90210",
  "country": "United States",
  "country abbreviation": "US",
  "places": [
    {
      "place name": "Beverly Hills",
      "longitude": "-118.4065",
      "state": "California",
      "state abbreviation": "CA",
      "latitude": "34.0901"
    }
  ]
}

Extracting Coordinates with jq

bash
# Get latitude
curl -s "https://api.zippopotam.us/us/10001" | jq -r '.places[0].latitude'

# Get longitude
curl -s "https://api.zippopotam.us/us/10001" | jq -r '.places[0].longitude'

# Get both as comma-separated
curl -s "https://api.zippopotam.us/us/10001" | jq -r '.places[0] | "\(.latitude),\(.longitude)"'

Response Fields

FieldDescription
post codeThe zip code queried
countryFull country name
country abbreviation2-letter country code (US)
placesArray of locations (usually 1 for zip codes)
places[].place nameCity/town name
places[].stateFull state name
places[].state abbreviation2-letter state code
places[].latitudeLatitude as string
places[].longitudeLongitude as string

Notes

  • Returns 404 for invalid zip codes
  • Coordinates are returned as strings, convert to float if needed
  • Data sourced from GeoNames
  • Some zip codes may have multiple places in the array

Option 2: OpenStreetMap Nominatim

More powerful geocoding API, but requires a User-Agent header and has rate limits.

Base URL

code
https://nominatim.openstreetmap.org

Endpoint Format

code
GET /search?postalcode={zip}&country=USA&format=json

Example CURL

bash
curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
  "https://nominatim.openstreetmap.org/search?postalcode=90210&country=USA&format=json"

Response Format

json
[
  {
    "place_id": 123456,
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0.",
    "lat": "34.0901",
    "lon": "-118.4065",
    "display_name": "90210, Beverly Hills, Los Angeles County, California, United States",
    "type": "postcode",
    "importance": 0.435
  }
]

Extracting Coordinates with jq

bash
curl -s -H "User-Agent: MyApp/1.0" \
  "https://nominatim.openstreetmap.org/search?postalcode=10001&country=USA&format=json" \
  | jq -r '.[0] | "\(.lat),\(.lon)"'

Important Requirements

RequirementDetails
User-AgentRequired - Must identify your application
Rate LimitMax 1 request per second
No Bulk QueriesCannot download complete lists of postcodes

When to Use Nominatim

  • Need additional address details
  • Need international postal codes beyond Zippopotam coverage
  • Building an application that also needs general geocoding

Comparison

FeatureZippopotam.usNominatim
API KeyNot requiredNot required
User-AgentNot requiredRequired
Rate LimitNone documented1 req/sec
US Coverage43,624 zip codesComprehensive
ResponseSimple JSONDetailed JSON
Best ForSimple zip lookupsGeneral geocoding

Recommendation

Use Zippopotam.us for simple US zip code to lat/long conversion. It's simpler, has no documented rate limits, and returns a clean, predictable response format.

Use Nominatim if you need additional geocoding capabilities beyond zip codes, or need the extra address details in the response.