Geocoding - Agents Studio Docs

Ejecuta la tool geocoding con la acción geocode para transformar direcciones libres en coordenadas, formattedAddress y metadatos del proveedor.

Requiere API Key con permiso tools:execute y el header X-Workspace-Id.

Ejecutar una geocodificación

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", {
  agentId: "38f62697-0f4b-49bc-8a0c-67256f5af6ff",
  action: "geocode",
  args: {
    query: "Av. Paseo de la Reforma 305, Ciudad de México",
    language: "es",
    region: "mx",
  },
});

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

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 '{
    "agentId": "38f62697-0f4b-49bc-8a0c-67256f5af6ff",
    "action": "geocode",
    "args": {
      "query": "Av. Paseo de la Reforma 305, Ciudad de México",
      "language": "es",
      "region": "mx"
    }
  }'

Respuesta típica

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

agentId es obligatorio en el body y debe ser un UUID v4: identifica al agente en cuyo contexto se ejecuta la tool. Si falta, la API responde 400.
Ajusta language y region para priorizar resultados locales.
El backend garantiza que action sea geocode; cualquier otro valor devuelve 400 Unsupported geocoding action.
Ante indisponibilidad del proveedor recibirás 503 Service Unavailable y puedes reintentar.

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