Trae tu propio buscador
Referencia de integración BYOS
Mantén Algolia, Typesense, Elasticsearch o Meilisearch como índice. Apunta los clientes a SuggestAPI; nosotros reescribimos, cacheamos, enrutamos y normalizamos las respuestas del motor subyacente.
Ruta de la solicitud
| Fase | Qué ocurre |
|---|---|
| Entrada en el edge | El cliente envía `GET /v1/autocomplete` o `POST /query` con una clave de SuggestAPI. TLS termina en el edge; los límites de tasa y la validación de solicitudes se ejecutan antes del trabajo en el origen. |
| Normalizar y reescribir | La consulta se recorta, se corrige ortográficamente y se amplía cuando `rewrite=true`. SuggestAPI registra `original_query`, `corrected_query` y `expanded_query` en la respuesta. |
| Búsqueda en caché | Las claves de autocompletado frecuentes se sirven desde la caché del edge cuando `cache=true` y la tupla índice/backend es cacheable. Los fallos pasan al adaptador configurado. |
| Ruta del adaptador | El enrutamiento por índice selecciona el adaptador de backend (`algolia`, `typesense`, `elastic`, `meilisearch` o `suggestapi`). Las credenciales del backend se inyectan en el servidor y nunca se devuelven al cliente. |
| Mapeo de respuesta | Los resultados del adaptador se normalizan en un único esquema JSON (`suggestions[]` con `id`, `type`, `title`, `subtitle`, `url`, etc.) independientemente de la forma del motor de origen. |
Ejemplos
Autocompletado (predeterminado en tiendas)
curl "https://api.suggestapi.com/v1/autocomplete" \
-G \
--data-urlencode "index=products" \
--data-urlencode "query=waterprof boots" \
--data-urlencode "limit=8" \
--data-urlencode "rewrite=true" \
-H "x-api-key: $SUGGESTAPI_KEY"Reemplaza las llamadas directas del cliente de búsqueda por este único GET. El enrutamiento del adaptador se configura por índice en SuggestAPI, no en la solicitud.
Consulta completa
curl -X POST "https://api.suggestapi.com/query" \
-H "Authorization: Bearer $SUGGESTAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"index": "products",
"query": "waterproof hiking boots",
"rewrite": true,
"cache": true
}'SuggestAPI resuelve el motor de origen desde la configuración de tu índice después de que la solicitud llegue a api.suggestapi.com. Los clientes solo envían consulta + índice.
Familias de endpoints
| Método | Ruta | Uso | Parámetros clave |
|---|---|---|---|
| GET | /v1/autocomplete | Typeahead y sugerencias de la barra de búsqueda. Superficie principal de integración BYOS para tiendas online. | `index`, `query`, `limit`, `rewrite` y `cache` opcionales |
| GET | /v1/typeahead | Completado orientado a prefijos cuando quieres cargas más ligeras que el autocompletado completo. | `index`, `query`, `limit` |
| POST | /query | Consultas de búsqueda completas con reescritura, caché y filtros. El enrutamiento del adaptador se resuelve desde la configuración de tu índice. | `index`, `query`, `rewrite`, `cache`, filtros |
Comprobación de estado: /health
Esquema de respuesta
{
"query": "waterproof hiking boots",
"original_query": "waterprof boots",
"corrected_query": "waterproof boots",
"expanded_query": "waterproof hiking boots",
"mode": "autocomplete",
"suggestions": [
{
"id": "sku-8842",
"type": "product",
"title": "Men's Waterproof Hiking Boots",
"subtitle": "Gore-Tex · size 10",
"url": "/products/sku-8842"
}
]
}| Campo | Significado |
|---|---|
| query | Consulta normalizada que procesó SuggestAPI |
| original_query | Entrada original del cliente antes de la reescritura |
| corrected_query | Forma corregida ortográficamente cuando la reescritura cambió la cadena |
| mode | Modo de sugerencia (`autocomplete`, `typeahead`, etc.) |
| suggestions[] | Resultados normalizados: la misma forma tanto si el origen era Algolia como Typesense |
| live | Indica si la respuesta vino de un adaptador en vivo o de un fallback estático (solo rutas de demo) |
Límite de confianza
| Ámbito | Contiene | Nunca ve |
|---|---|---|
| Navegador / móvil / cliente de agente | Clave de API de SuggestAPI (`x-api-key` o `Authorization: Bearer`) | Clave de administración de Algolia, clave de API de Typesense, credenciales de Elastic |
| Edge y plano de control de SuggestAPI | Credenciales del adaptador de backend, reglas de enrutamiento por índice, claves de caché, eventos de analítica | PII del usuario final, salvo que la envíes en los parámetros de consulta |
| Tu backend de búsqueda | Documentos del índice, configuración de ranking, reglas de sinónimos, topología de réplicas | Otros tenants, índices no relacionados, secretos del lado del cliente |
Configuración del adaptador
- Asigna cada slug de `index` de SuggestAPI a un adaptador de backend y a un nombre de índice de origen.
- Guarda las credenciales de Algolia / Typesense / Elastic en SuggestAPI, no en el bundle de tu SPA ni en el manifiesto del agente.
- Apunta staging a Typesense y producción a Algolia cambiando el enrutamiento del índice, no el código del cliente.
- Ejecuta tráfico en la sombra: duplica consultas a un backend candidato y compara latencia o calidad de resultados en la analítica.
Operaciones
Comportamiento de caché
El autocompletado con cache=true sirve prefijos repetidos desde el edge. El TTL depende del índice; invalida la caché cuando reindexes por lotes en el origen.
Modos de fallo
Los timeouts o las respuestas 5xx del adaptador se muestran como sugerencias degradadas; configura fallbacks por índice. Los límites de tasa devuelven cargas de muestra o en caché en lugar de exponer errores del origen a los clientes.
Observabilidad
Cada consulta enrutada emite analítica: consulta original, delta de reescritura, adaptador de backend, latencia y clics cuando conectas el píxel de seguimiento o los eventos del servidor.