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

# GET /agri/geocode — Search LATAM locations

> Search for LATAM locations by name using Open-Meteo Geocoding and retrieve coordinates, administrative details, elevation, and population for each result.

The geocode endpoint lets you search for a location by name and retrieve its geographic coordinates along with administrative metadata. It is backed by the Open-Meteo Geocoding API and is oriented toward Latin American regions. You can use it to resolve a user-entered place name into latitude/longitude before calling other endpoints such as `/agri/advisor` or `/fires/hotspots`.

## Endpoint

```text theme={null}
GET api.climatifai.com/agri/geocode
```

## Parameters

<ParamField query="q" type="string" required>
  Location name to search. Can be a city, municipality, region, or other place name. Example: `"Oaxaca"`, `"Valle del Cauca"`, `"Cochabamba"`.
</ParamField>

<ParamField query="count" default="5" type="integer">
  Maximum number of results to return. The API returns the top matches ranked by relevance.
</ParamField>

## Response

<ResponseField name="results" type="array" required>
  Array of matching locations. May be empty if no results are found.

  <Expandable title="Location object properties">
    <ResponseField name="name" type="string">
      Display name of the location.
    </ResponseField>

    <ResponseField name="lat" type="float">
      Latitude in decimal degrees, WGS 84.
    </ResponseField>

    <ResponseField name="lon" type="float">
      Longitude in decimal degrees, WGS 84.
    </ResponseField>

    <ResponseField name="country" type="string">
      Country name. Example: `"Mexico"`.
    </ResponseField>

    <ResponseField name="admin1" type="string">
      First-level administrative division (state, department, or province). May be `null` for some entries.
    </ResponseField>

    <ResponseField name="elevation" type="float">
      Elevation above sea level in metres. May be `null`.
    </ResponseField>

    <ResponseField name="population" type="integer">
      Approximate population of the location. May be `null` for rural areas or administrative regions.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error codes

| Code  | Description                                                   |
| ----- | ------------------------------------------------------------- |
| `502` | Upstream error from the Open-Meteo Geocoding service.         |
| `503` | Open-Meteo rate limit exceeded. Retry after a short back-off. |

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.climatifai.com/agri/geocode?q=Oaxaca&count=3"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "results": [
      {
        "name": "Oaxaca",
        "lat": 17.0667,
        "lon": -96.7167,
        "country": "Mexico",
        "admin1": "Oaxaca",
        "elevation": 1555.0,
        "population": 258008
      },
      {
        "name": "Oaxaca de Juárez",
        "lat": 17.0606,
        "lon": -96.7254,
        "country": "Mexico",
        "admin1": "Oaxaca",
        "elevation": 1531.0,
        "population": 264968
      },
      {
        "name": "San Pablo Villa de Mitla",
        "lat": 16.9247,
        "lon": -96.4019,
        "country": "Mexico",
        "admin1": "Oaxaca",
        "elevation": 1520.0,
        "population": 11102
      }
    ]
  }
  ```
</ResponseExample>