Envia Geocodes API – Overview

The Geocodes API provides address validation and geocoding services. Use it to verify postal codes, locate cities, and retrieve geographic coordinates before creating shipments. Validating addresses upfront reduces failed deliveries and carrier rejections.

Endpoints

The Geocodes API has two endpoints:

Environments

The Geocodes API has a single production base URL. No sandbox environment exists. Authentication is not required — you can call the Geocodes API without a Bearer token.

Validate a postal code

Use GET /zipcode/{country}/{zipcode} to verify that a postal code exists and retrieve the associated city, state, and geographic coordinates.

curl --request GET \
  --url https://geocodes.envia.com/zipcode/MX/64060

Successful response:

{
  "success": true,
  "data": {
    "zipcode": "64060",
    "city": "Monterrey",
    "state": "NL",
    "country": "MX",
    "coordinates": {
      "latitude": "25.6866",
      "longitude": "-100.3161"
    }
  }
}

If the postal code does not exist, the API returns:

{
  "success": false,
  "message": "Zip code not found"
}

Locate a city

Use GET /locate/{country}/{city} to find all postal codes associated with a city. This is useful when you have a city name but need the postal code for address completion.

curl --request GET \
  --url https://geocodes.envia.com/locate/MX/Monterrey

The response contains an array of locations since a city can have multiple postal codes:

{
  "success": true,
  "data": [
    {
      "city": "Monterrey",
      "state": "NL",
      "country": "MX",
      "zipcode": "64000",
      "coordinates": {
        "latitude": "25.6866",
        "longitude": "-100.3161"
      }
    },
    {
      "city": "Monterrey",
      "state": "NL",
      "country": "MX",
      "zipcode": "64010",
      "coordinates": {
        "latitude": "25.6866",
        "longitude": "-100.3161"
      }
    }
  ]
}

When to use Geocodes vs Queries vs Shipping

A typical integration flow:

1. Validate the address with the Geocodes API (verify postal code, get city/state)
2. Discover available carriers with the Queries API (check services for the route)
3. Execute shipping with the Shipping API (rate, create label, track)

Supported countries

The Geocodes API supports address validation for all countries where Envia operates. Use the 2-letter ISO country code in the URL path:

💡

If a country code returns no results, it may not have postal code data in the Geocodes database. Use the envia_list_countries tool or the Countries endpoint in the Queries API to confirm which countries are supported.

Common use cases

• Validate postal codes before creating shipments to prevent carrier rejections
• Auto-complete address forms by filling in city and state from a postal code
• Get GPS coordinates for mapping delivery locations and calculating distances
• Verify that a destination is serviceable before showing shipping options to customers

Tip: Always validate the destination postal code before requesting rates. Invalid addresses are the most common cause of label creation failures.

What to read next

• Plan your integration – The Integration Guide uses the Geocodes API in Phase 2 for address validation.
• Discover carriers – After validating addresses, use the Queries API to find available carriers and services.
• Start shipping – The Shipping API Overview covers rate quotes, labels, and tracking.