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

# Geocoding

> Obtén coordenadas y direcciones normalizadas con la tool `geocoding`.

<Note>
  Ejecuta la tool <code>geocoding</code> con la acción <code>geocode</code> para
  transformar direcciones libres en coordenadas, <em>formattedAddress</em> y
  metadatos del proveedor.
</Note>

<Info>
  Requiere API Key con permiso <code>tools:execute</code> y el header
  <code>X-Workspace-Id</code>.
</Info>

## Ejecutar una geocodificación

<CodeGroup>
  ```ts theme={null}
  import { createClient } from "@getsupervisor/agents-studio-sdk";

  const client = createClient({
  baseUrl: process.env.API_BASE_URL!,
  workspaceId: process.env.WORKSPACE_ID!,
  apiKey: process.env.API_KEY!,
  });

  const response = await client.tools.execute("geocoding", {
  action: "geocode",
  args: {
  query: "Av. Paseo de la Reforma 305, Ciudad de México",
  language: "es",
  region: "mx",
  },
  });

  console.log(response.result.matches[0]);

  ```

  ```bash theme={null}
  curl --request POST \
    --url "$API_BASE_URL/v1/tools/geocoding/execute" \
    --header "X-API-Key: $API_KEY" \
    --header "X-Workspace-Id: $WORKSPACE_ID" \
    --header "Content-Type: application/json" \
    --data '{
      "action": "geocode",
      "args": {
        "query": "Av. Paseo de la Reforma 305, Ciudad de México",
        "language": "es",
        "region": "mx"
      }
    }'
  ```
</CodeGroup>

## Respuesta típica

```json theme={null}
{
  "status": "ok",
  "result": {
    "query": "Av. Paseo de la Reforma 305, Ciudad de México",
    "matches": [
      {
        "formattedAddress": "Av. Paseo de la Reforma 305, Cuauhtémoc, 06500 Ciudad de México, CDMX, México",
        "location": { "lat": 19.426991, "lng": -99.167663 },
        "placeId": "ChIJrUu1BekB0oUR1dCLfuOGnMo",
        "types": ["street_address"],
        "score": 0.97
      }
    ],
    "raw": {
      "provider": "google_maps",
      "responseTimeMs": 312
    }
  },
  "metadata": {
    "provider": "google_maps",
    "matchCount": 1,
    "resolvedAt": "2025-10-30T19:21:14.610Z",
    "language": "es",
    "region": "mx"
  }
}
```

## Buenas prácticas

* Ajusta <code>language</code> y <code>region</code> para priorizar resultados locales.
* El backend garantiza que <code>action</code> sea <code>geocode</code>; cualquier otro valor devuelve <code>400 Unsupported geocoding action</code>.
* Ante indisponibilidad del proveedor recibirás <code>503 Service Unavailable</code> y puedes reintentar.

<Info>
  La respuesta puede incluir campos adicionales dentro de <code>matches</code>
  dependiendo del proveedor configurado (Google, Mapbox, etc.).
</Info>