> ## Documentation Index
> Fetch the complete documentation index at: https://docs.climatifai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geographic coverage and location handling

> Understand AgroRisk's LATAM coverage, how coordinates are resolved and cached, and which countries and regions are supported across all endpoints.

AgroRisk covers agricultural regions across Latin America (LATAM), excluding Brazil. Every endpoint accepts standard decimal latitude and longitude coordinates — there are no location IDs to manage or region codes to look up. If you have a place name but not coordinates, the `/agri/geocode` endpoint resolves it for you.

## Geographic coverage

All climate, scoring, and fire risk endpoints operate over LATAM excluding Brazil. The exclusion of Brazil (`ISO 3166-1 alpha-2: BR`) is enforced systematically across all location-aware endpoints: queries with coordinates inside Brazil may not return data, and the `country_iso` parameter rejects `BR` values.

Supported countries include Mexico, Guatemala, Belize, Honduras, El Salvador, Nicaragua, Costa Rica, Panama, Colombia, Venezuela, Ecuador, Peru, Bolivia, Chile, Argentina, Paraguay, Uruguay, and the Caribbean nations of LATAM.

<Warning>
  Brazil is excluded from all location-aware endpoints. Passing coordinates within Brazil or `country_iso=BR` will not produce results and may return an error.
</Warning>

## Using coordinates

All endpoints accept `lat` and `lon` as decimal degree values. There are no region enums, location IDs, or bounding boxes to configure for standard queries — just pass the coordinate of interest.

```bash theme={null}
# Crop aptitude score for a location in Oaxaca, Mexico
GET api.climatifai.com/agri/advisor?lat=17.06&lon=-96.72&crop_id=cafe&season=lluvias

# Fire risk for the Chaco region of Paraguay
GET api.climatifai.com/fires/risk?lat=-22.0&lon=-60.0&radius_km=150

# Historical climate for the Andean highlands of Peru
GET api.climatifai.com/agri/climate?lat=-13.0&lon=-75.0&from=2000&to=2022
```

## Geocoding place names

If you have a place name rather than coordinates, use `/agri/geocode` to search for LATAM locations by name. The endpoint returns up to five results by default, each with a name, country, administrative region, elevation, and coordinates ready to pass to other endpoints.

```bash theme={null}
GET api.climatifai.com/agri/geocode?q=Oaxaca&count=3
```

```json theme={null}
{
  "results": [
    {
      "name": "Oaxaca",
      "lat": 17.0732,
      "lon": -96.7266,
      "country": "Mexico",
      "admin1": "Oaxaca",
      "elevation": 1555.0,
      "population": 263357
    }
  ]
}
```

## Coordinate rounding and cache consistency

Internally, all coordinates are rounded to four decimal places before being used as cache keys or stored in the database. This means that `lat=20.50001` and `lat=20.5000` resolve to the same cached record. For best cache hit rates, round your coordinates to four decimal places before making repeated calls to the same location.

## The `country_iso` parameter

The `country_iso` parameter is accepted by `/agri/advisor` and `/agri/climate`. It is optional for most use cases.

When provided, supply a valid LATAM ISO 3166-1 alpha-2 code (e.g., `MX`, `CO`, `AR`). The value must not be `BR` (Brazil). On deployments with location tracking enabled, this associates the climate data with a named country entry for reporting purposes.

<Note>
  You do not need `country_iso` to get crop scoring, climate data, or fire risk results. Omitting it has no effect on the API response.
</Note>

## Example LATAM agricultural regions

The following table lists representative agricultural coordinates across LATAM to help you get started:

| Region              | Country            | Lat   | Lon    | Key crops                 |
| ------------------- | ------------------ | ----- | ------ | ------------------------- |
| Bajío               | Mexico             | 20.5  | -101.0 | Maize, sorghum, wheat     |
| Oaxaca highlands    | Mexico             | 17.1  | -96.7  | Coffee, maize             |
| Centroamérica       | Guatemala/Honduras | 14.0  | -87.0  | Coffee, cardamom, banana  |
| Llanos Orientales   | Colombia           | 4.0   | -72.5  | Rice, soybean             |
| Orinoquía           | Colombia/Venezuela | 6.5   | -68.0  | Maize, sorghum, cotton    |
| Sierra Peruana      | Peru               | -13.0 | -75.0  | Potato, quinoa            |
| Chaco               | Paraguay/Argentina | -22.0 | -60.0  | Soybean, cotton, sorghum  |
| Pampa Húmeda        | Argentina          | -34.0 | -61.0  | Wheat, soybean, maize     |
| Valle Central       | Chile              | -34.5 | -71.0  | Grapevine, avocado, wheat |
| Altiplano boliviano | Bolivia            | -16.5 | -68.1  | Quinoa, potato            |
| Costa Ecuatoriana   | Ecuador            | -1.8  | -79.9  | Banana, cacao, rice       |
| Cundinamarca        | Colombia           | 5.0   | -74.0  | Coffee, potato            |

<Tip>
  Use `/agri/geocode` with the region names in the table above to retrieve precise coordinates and elevation data before running scoring or climate queries.
</Tip>