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:

Environment and authentication

⚠️

The Geocodes API is available only in production. There is no sandbox environment for this service. Use your production API key when calling these endpoints.

The Geocodes API uses the same Bearer token as the Shipping and Queries APIs. Include it in every request via the Authorization: Bearer <token> header. Generate tokens in your Envia dashboard under Desarrolladores → Acceso de API.

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 \
  --header "Authorization: Bearer $ENVIA_TOKEN"

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 \
  --header "Authorization: Bearer $ENVIA_TOKEN"

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)

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.