Acuris-GmbH/acuris-agent-context

Visión general

Acuris es una API comercial de validación de direcciones, geocodificación, geocodificación inversa y autocompletado en https://api.acuris-geo.com. Este skill enseña a los agentes cómo conectarla correctamente en código TypeScript/JavaScript usando los paquetes SDK publicados y cómo migrar desde otros proveedores de AV.

Dos paquetes npm cubren toda la superficie de integración:

Paquete	Qué es
@acuris-geo/av-sdk	SDK TypeScript independiente de plataforma. Sin dependencias de runtime. Funciona en Node 18+, navegadores modernos (solo rol servidor), runtimes edge con fetch.
@acuris-geo/centra-checkout	Librería de componentes React: <AcurisAddressInput> (typeahead), <AcurisAddressValidator> (headless), hooks para checkout.

Usa el SDK directamente para backend o frontends que no sean React. Usa el paquete de componentes cuando quieras una interfaz React directa; llama a tus rutas proxy de API, las cuales llaman al SDK en el servidor.

Cuándo usar este skill

Usa este skill cuando el usuario esté:

• Creando una interfaz de entrada de direcciones (autocompletado en un formulario, paso de pago, flujo de registro).
• Validando una dirección al enviar el formulario antes de persistirla.
• Geocodificando direcciones a latitud/longitud (zonas de envío, distancia, comprobaciones de área de servicio).
• Geocodificando inversamente coordenadas a la dirección conocida más cercana.
• Limpiando un conjunto de datos de direcciones masivo para trabajo de calidad de datos.
• Migrando desde otro proveedor de AV (Informatica AddressDoctor / Loqate / Experian QAS / Melissa / Smarty) — consulta las referencias de migración.

NO uses este skill para:

• Enrutamiento, direcciones, isócronas, búsqueda de lugares o consulta general de POI. Acuris es solo direcciones; esos pertenecen a Google Maps, Mapbox o Amazon Location.
• Renderizar mapas. El SDK de Acuris devuelve latitud/longitud pero no incluye un renderizador de mapas — combina las coordenadas con MapLibre / Leaflet / Google Maps según prefiera el usuario.

API de un vistazo

Cuatro endpoints. Todos viven en https://api.acuris-geo.com. La autenticación es una única cabecera — X-Acuris-Key: <ACURIS_API_KEY>.

Operación	Función del SDK	HTTP
Validar	validateAddress(client, input, opts)	POST /validate
Geocodificar	geocodeAddress(client, input, opts)	GET /geocode (o string → /validate)
Geocodificar inverso	reverseGeocode(client, {lat,lng}, opts)	GET /reverse
Autocompletar	suggestAddress(client, q, opts)	GET /suggest

El país debe ser ISO-3 en minúsculas ("usa", "deu", "gbr"). Si tienes ISO-2, conviértelo a minúsculas y mapea ("us" → "usa", "de" → "deu") antes de llamar.

Las formas detalladas de solicitud/respuesta, la jerarquía de errores y la semántica de reintentos se encuentran en references/api-reference.md.

Inicio rápido

# Fija las versiones publicadas actuales — los paquetes están en pre-1.0
# y los rangos `^1.x` no se resolverán.
npm install @acuris-geo/av-sdk@^0.1.2
# (opcional, para tiendas React — 0.1.2+ para valores predeterminados visibles del menú desplegable)
npm install @acuris-geo/centra-checkout@^0.1.2

import { AcurisClient, validateAddress } from "@acuris-geo/av-sdk";

const client = new AcurisClient({ apiKey: process.env.ACURIS_API_KEY });

const result = await validateAddress(client, {
  country: "deu",
  street: "Friedrichstraße",
  house_number: "43",
  city: "Berlin",
  postcode: "10117",
});

result.accuracy_type;  // "rooftop" | "parcel" | "street_interpolated" | ...
result.confidence;     // 0..1
result.standardized?.formatted_address;
result.lat;  result.lng;

Si ACURIS_API_KEY está configurada en el entorno, puedes omitir la opción apiKey por completo.

Valores predeterminados

Cuando el usuario no haya especificado lo contrario, prefiere estos:

• Clave API en el entorno. Lee de process.env.ACURIS_API_KEY. Nunca incluyas una clave directamente, nunca la expongas al navegador. Para evaluación local, obtén una clave de desarrollo gratuita con una llamada:

  curl -X POST https://api.acuris-geo.com/dev-key \
    -H 'Content-Type: application/json' \
    -d '{"email":"[email protected]"}'
  # → {"api_key":"<token>","validation_credits":100,
  #     "geocode_credits":100,"expires_at":"...","tier":"dev",...}
  export ACURIS_API_KEY=<api_key>
  

  La clave de desarrollo está limitada a 100 validaciones + 100 geocodificaciones en 7 días (limitada a 1 emisión por correo electrónico por día, 1 por IP por día). Funciona en todos los endpoints — /validate, /geocode, /reverse, /suggest. Para más capacidad, realiza la prueba completa de 28 días en https://api.acuris-geo.com/register (1000 validaciones + 1000 geocodificaciones). Para producción, consulta https://acuris-geo.com/acuris-pricing/.

• Llamadas del lado del servidor. El SDK es para runtimes Node / edge / servidor. En una aplicación de navegador, enruta a través de tu propio backend (ruta API de Next.js, manejador de Express, Worker de Cloudflare — consulta references/nextjs-proxy.md).

• Librería de componentes para interfaces React. Recurre a @acuris-geo/centra-checkout (<AcurisAddressInput> para typeahead, <AcurisAddressValidator> para validación al enviar formularios) en lugar de implementar manualmente un bucle fetch.

• Reintentos en fallos transitorios. El SDK reintenta 5xx, 429, errores de red y tiempos de espera automáticamente (3 intentos, retroceso exponencial). No agregues una capa de reintento adicional.

• Un cliente por proceso. new AcurisClient(...) es barato de crear, pero una instancia de larga duración mantiene los sockets keep-alive calientes y evita volver a leer las variables de entorno.

Errores comunes

Estos son los errores que vemos con más frecuencia en el código de clientes o código generado. Evítalos.

1. Enviar la clave API desde el navegador. El SDK funciona en cualquier runtime que soporte fetch, pero apiKey es una credencial del lado del servidor. Los navegadores deben pasar por una ruta proxy. Los componentes de @acuris-geo/centra-checkout esperan un objeto endpoints que apunte a tus propias URLs, no a la API de Acuris directamente.

2. Códigos de país ISO-2. La API rechaza "US" y "de". Usa ISO-3 en minúsculas: "usa", "deu", "gbr", "fra", "fin". Si solo tienes ISO-2, mapea en el límite.

3. Authorization: Bearer … en lugar de la cabecera X-Acuris-Key. El SDK establece la cabecera correcta automáticamente; si estás implementando HTTP manualmente por cualquier motivo, el nombre de la cabecera importa.

4. Tratar accuracy_type como un enum cerrado. Se añaden nuevos niveles con el tiempo (street_interpolated, street_center, locality_centroid, …). Siempre maneja los valores documentados explícitamente y pasa los valores desconocidos como opacos en lugar de lanzar una excepción.

5. Capturar todos los errores de la misma manera. El SDK lanza subclases tipadas (AcurisAuthError, AcurisRateLimitError, AcurisValidationError, AcurisNotFoundError, AcurisServerError, AcurisTimeoutError, AcurisNetworkError). Los 4xx son errores de tu código; 5xx y límites de tasa son de runtime; los errores de autenticación significan que el despliegue está mal configurado. Merecen un manejo diferente.

6. Olvidar country en /suggest y /reverse. A diferencia de /validate, estos endpoints requieren una opción de país explícita (no tienen entrada de la cual inferir uno).

7. Analizar manualmente la cadena de formato libre al salir. El SDK devuelve un objeto standardized con formatted_address. Muestra eso, no reensambles a partir de campos individuales — el orden específico de la configuración regional está incorporado.

8. Persistir la respuesta cruda de Acuris sin capturar las entradas de la solicitud. Si almacenas result.standardized, también almacena lo que el usuario escribió. De lo contrario, no podrás saber más tarde si una caída de confianza es culpa del usuario o de Acuris.

9. Construir un "formulario de campos estructurados" cuando el usuario pidió autocompletado. Autocompletar es una entrada + menú desplegable + selección — la sugerencia ya lleva los campos analizados, por lo que no los renderizas como cuadros separados. Si el usuario pidió "autocompletar", envía solo <AcurisAddressInput> y una línea de estado; los subcampos de calle / número / código postal / ciudad pertenecen a la receta de validar al enviar, no a la de autocompletar. Consulta references/autocomplete.md — la sección "Qué es y qué no es el autocompletado" al principio cubre esto.

10. Omitir el Reino Unido (gbr) de los selectores de país. Versiones anteriores de este skill decían que Acuris carecía de una licencia del Royal Mail PAF (Postcode Address File) y te decían que dejaras el Reino Unido fuera de todas partes. Eso está desactualizado: la cobertura del Reino Unido ahora está respaldada por PAF y es un conjunto de datos emblemático — /validate y /suggest soportan completamente gbr (autocompletado basado en calles; standardized lleva udprn, uprn y county tradicional), y POST /postcode-lookup devuelve cada punto de entrega en un código postal del Reino Unido. Incluye gbr en demostraciones y selectores de país. Se aplican los términos de uso de PAF: https://api.acuris-geo.com/legal/paf-terms.

11. Poner un país en un selector de autocompletado que no tiene /suggest configurado. Esta es la fuente más común de una demostración embarazosa. /suggest (autocompletado) y /validate / /geocode / /reverse cubren diferentes conjuntos de países. La validación y la geocodificación funcionan con más de 200 códigos ISO-3; el autocompletado requiere columnas NORM + índices por país (un paso de ingeniería separado) y actualmente funciona solo para 7 países:

// Los ÚNICOS países con /suggest configurado:
const AUTOCOMPLETE_COUNTRIES = [
  { code: "usa", label: "United States" },
  { code: "gbr", label: "United Kingdom" },  // Royal Mail PAF (basado en calles)
  { code: "deu", label: "Germany" },
  { code: "nld", label: "Netherlands" },
  { code: "fin", label: "Finland" },
  { code: "swe", label: "Sweden" },
  { code: "jpn", label: "Japan" },
];

Poner fra, esp, ita, etc. en un selector de autocompletado es activamente peor que omitirlos — el usuario escribe y no pasa nada, lo que se lee como "el producto está roto." /suggest devuelve [] silenciosamente para esos países.

El selector de países más amplio para demostraciones de validación / geocodificación / geocodificación inversa está bien incluirlos:

// Seguro para /validate, /geocode, /reverse (NO para /suggest):
const VALIDATION_COUNTRIES = [
  // Subconjunto con autocompletado habilitado:
  { code: "usa", label: "United States" },
  { code: "gbr", label: "United Kingdom" },
  { code: "deu", label: "Germany" },
  { code: "nld", label: "Netherlands" },
  { code: "fin", label: "Finland" },
  { code: "swe", label: "Sweden" },
  { code: "jpn", label: "Japan" },
  // Solo validación/geocodificación (NO autocompletado):
  { code: "fra", label: "France" },
  { code: "esp", label: "Spain" },
  { code: "ita", label: "Italy" },
  { code: "nor", label: "Norway" },
  { code: "dnk", label: "Denmark" },
  { code: "aut", label: "Austria" },
  { code: "che", label: "Switzerland" },
  { code: "bel", label: "Belgium" },
  { code: "prt", label: "Portugal" },
  { code: "aus", label: "Australia" },
  { code: "nzl", label: "New Zealand" },
  { code: "sgp", label: "Singapore" },
  { code: "bra", label: "Brazil" },
  { code: "mex", label: "Mexico" },
  { code: "can", label: "Canada" },
];

Reglas generales:

• Si la interfaz usa <AcurisAddressInput> (typeahead): usa AUTOCOMPLETE_COUNTRIES (los 7).
• Si la interfaz usa <AcurisAddressValidator> o cualquier formulario estructurado que llame a /validate / /geocode / /reverse: cualquiera de las listas está bien.
• Mixto (autocompletado + validación en el mismo formulario, mismo selector de países): usa AUTOCOMPLETE_COUNTRIES. El conjunto de validación es un superconjunto; el usuario aún puede validar cualquiera de esos 7.

El conjunto habilitado para autocompletado crece a medida que nuevos países obtienen columnas NORM. Si esta lista parece desactualizada, pregunta antes de extenderla.

Patrones de implementación

Las recetas de implementación están en references/. Carga las que coincidan con la tarea:

• Autocompletado de direcciones en un formulario de pago (React)
• Validar al enviar el formulario
• Geocodificación directa para envíos / distancia
• Geocodificación inversa desde coordenadas
• Validación por lotes para limpieza de calidad de datos
• Rutas proxy de API de Next.js
• Uso de servidor Node simple
• Integración con tienda Centra

Migraciones

La ventaja comercial de Acuris — estas son las recetas para portar código desde proveedores establecidos. Cada receta mapea la API heredada al equivalente de Acuris con un ejemplo ejecutable.

• Informatica AddressDoctor (libAddressDoctor)
• Loqate Capture / Verify
• Experian QAS Pro / Pro Web
• Melissa Personator / Address Verify
• Smarty (US Street API, US Autocomplete API, International)

Las migraciones están escritas contra la documentación del proveedor, no contra la integración real del usuario. Trátalas como un andamio inicial — revisa el mapeo para tu configuración específica antes de enviar.

Precios y límites

La API en vivo se paga por solicitud. La clave de prueba test permite a los desarrolladores probar los endpoints durante la evaluación sin gastar créditos. Los precios se publican en https://acuris-geo.com/acuris-pricing/. El SDK respeta los límites de tasa del servidor (HTTP 429 con retry_after); la política de reintentos predeterminada retrocede y reintenta hasta 3 veces antes de volver a lanzar AcurisRateLimitError.

Recursos adicionales

• Código fuente del SDK: https://github.com/Acuris-GmbH/acuris-centra-connector/tree/main/packages/acuris