---
updatedAt: 2026-07-07T05:00:34.000Z
agentTools:
  projectIndex: https://docs.envia.com/llms.txt
---

# 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:

| Endpoint                       | Method | Description                                                      |
| :----------------------------- | :----- | :--------------------------------------------------------------- |
| `/zipcode/{country}/{zipcode}` | GET    | Validate a postal code and get city, state, and coordinates      |
| `/locate/{country}/{city}`     | GET    | Find a city by name and get postal codes, state, and coordinates |

## 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.

| Base URL                      |
| :---------------------------- |
| `https://geocodes.envia.com/` |

## 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.

<Tabs>
  <Tab title="cURL">

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

  </Tab>

  <Tab title="JavaScript">

```javascript
var response = await fetch("https://geocodes.envia.com/zipcode/MX/64060");
var data = await response.json();
console.log(data);
```

  </Tab>

  <Tab title="Python">

```python
import requests

response = requests.get(
    "https://geocodes.envia.com/zipcode/MX/64060"
)
data = response.json()
print(data)
```

  </Tab>
</Tabs>

Successful response:

```json
{
  "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:

```json
{
  "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.

<Tabs>
  <Tab title="cURL">

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

  </Tab>

  <Tab title="JavaScript">

```javascript
var response = await fetch("https://geocodes.envia.com/locate/MX/Monterrey");
var data = await response.json();
console.log(data);
```

  </Tab>

  <Tab title="Python">

```python
response = requests.get(
    "https://geocodes.envia.com/locate/MX/Monterrey"
)
data = response.json()
print(data)
```

  </Tab>
</Tabs>

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

```json
{
  "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

| API      | Use when you need to                                               |
| :------- | :----------------------------------------------------------------- |
| Geocodes | Validate postal codes, locate cities, get coordinates              |
| Queries  | Discover carriers, services, countries, states, webhook management |
| Shipping | Execute shipping operations: rate, label, track, pickup, cancel    |

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:

| Country   | Code | Example postal code |
| --------- | :--: | :-----------------: |
| Argentina |  AR  |        C1001        |
| Brazil    |  BR  |      01310-100      |
| Canada    |  CA  |       M5V 2T6       |
| Chile     |  CL  |       7500000       |
| Colombia  |  CO  |        110111       |
| Spain     |  ES  |        28001        |
| France    |  FR  |        75001        |
| Guatemala |  GT  |        01001        |
| India     |  IN  |        110001       |
| Italy     |  IT  |        00100        |
| Mexico    |  MX  |        64000        |
| USA       |  US  |        10001        |

<Callout icon="💡" theme="default">
  ###

  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](https://docs.envia.com/reference/all-countries) in the Queries API to confirm which countries are supported.
</Callout>

## 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](https://docs.envia.com/docs/integration-guide) uses the Geocodes API in Phase 2 for address validation.
* **Discover carriers** – After validating addresses, use the [Queries API](https://docs.envia.com/docs/queries-api-overview) to find available carriers and services.
* **Start shipping** – The [Shipping API Overview](https://docs.envia.com/docs/envia-shipping-api-introduction) covers rate quotes, labels, and tracking.

<br />