API de búsqueda de alimentos

Qué hace una petición de búsqueda

Una búsqueda es un único GET con el texto en q. Las palabras se comparan a la vez con el nombre del producto y con la marca, así que q=olympus milk encuentra productos cuyo nombre nunca dice Olympus, y la última palabra se trata como prefijo, de modo que milk olym ya coincide mientras el usuario todavía está escribiendo. Deben coincidir todas las palabras; no existe el OR. q debe tener entre 1 y 200 caracteres; una q ausente o vacía se rechaza antes de ejecutar ninguna búsqueda, así que protege tú el cuadro de búsqueda vacío.

Los productos que se llaman exactamente como lo que escribiste van primero, de modo que banana lista las bananas antes que los yogures de banana y greek yogurt lista los yogures griegos naturales antes que el resto. Después, los resultados se ordenan por relevancia y, cuando dos productos coinciden igual de bien, se lista primero el más popular. Una consulta de marca como pringles se salta el paso del nombre exacto y se queda en orden de popularidad; añadir una segunda palabra (una marca, un sabor) es la forma más rápida de subir un producto concreto.

Los nombres de categoría son un recurso de reserva, no parte de la coincidencia principal: solo cuando la búsqueda por nombre y marca no encuentra nada, la API busca productos cuya categoría contenga las palabras, en el idioma en que esté guardada la categoría. Por eso una consulta como Seeds & Related Snacks o Fruits tropicaux devuelve una lista, ordenada por popularidad, en lugar de un array vacío.

• El orden no es alfabético ni por id. No vuelvas a ordenar el array data en el cliente.
• Si la entrada es un GTIN de solo dígitos, envíala a la API de consulta de códigos de barras: resuelve las variantes con ceros a la izquierda (0000080042556 encuentra 80042556), cosa que una búsqueda de texto no hace.

Cómo leer una fila de resultado

Cada elemento de data es un FoodListItem, una forma más ligera que el registro completo: id, barcode, source, name_default, brand, category, image_url, nutriscore y nova_group, además de name_localized (siempre presente) y category_localized cuando se pasa un lang distinto del inglés. Aquí no hay nutrientes; la lista está pensada para pintar filas, no para hacer cálculos.

Varios campos admiten null, y la muestra lo refleja. El caramelo Roshen 'Banana land' (4f995c13-c0df-bfcc-b6ec-449d312def75) tiene image_url null y nova_group null; brand y barcode también pueden ser null. Los valores de nutriscore fuera de a–e, como la 'n' y la 'u' de la muestra, significan que no se calculó ninguna nota, así que muéstralos como «sin calificar» en lugar de la letra en bruto.

category es la ruta completa de categorías de Open Food Facts, separada por comas de lo general a lo específico ('...,Fruits tropicaux,Bananes' para las bananas de Bio Village). Muestra el último segmento como etiqueta, o el primero para una agrupación gruesa, y quita prefijos de idioma como pt: antes de mostrarlo. image_url es una foto de un colaborador en images.openfoodfacts.org, así que prepara un marcador de posición para el caso null.

Paginación, total e ids estables

limit va de 1 a 100 (por defecto 20) y offset de 0 a 10000. total es un recuento con tope: la API deja de contar en 1000 coincidencias, así que el total de 1000 de la muestra para q=banana con limit=3 significa «al menos 1000». Muéstralo como '1000+' y no calcules un número de última página a partir de él.

Pagina sumando limit a offset hasta que data devuelva menos de limit elementos. Como offset tiene un máximo de 10000, una consulta con más coincidencias necesita una q más acotada, no una página más profunda.

• Los ids son estables entre reimportaciones de FoodBase, así que guarda el id de una fila de búsqueda y resuélvelo más tarde con la API de base de datos de alimentos sin volver a buscar.
• El ranking se calcula en cada petición y la popularidad puede cambiar, por lo que un offset no es un cursor duradero. Guarda ids, no posiciones de página.

Buscar en otro idioma

lang vale en por defecto. Cada idioma busca en la entrada de ese idioma del array de nombres del producto cuando un voluntario o la traducción por IA de FoodBase ha aportado una, y recurre a name_default, el nombre tal como está impreso en la etiqueta, para los productos que no tienen esa entrada; la marca siempre forma parte de la coincidencia. Así, lang=bg llega a todos los productos, pero prefiere los nombres en búlgaro donde existen, y una etiqueta en cirílico se encuentra con cualquier lang.

El lang que pasas también da forma a la salida. name_localized contiene el nombre traducido: la muestra, solicitada con lang=en, convierte 'Puré de plátano y fresa' en 'Banana and Strawberry Puree' y recurre a name_default cuando no hay nada que traducir, como muestra 'Banana land'. Muestra name_localized cuando no sea null y name_default en caso contrario. category_localized no es un campo obligatorio y no aparece en la muestra, así que léelo a la defensiva.

Autocompletado y el traspaso a registros completos

La búsqueda es el endpoint adecuado para un cuadro de escritura predictiva. Aplica debounce a las pulsaciones, pide limit=8 o 10 y cancela la petición en curso cuando el usuario vuelva a escribir, para que una respuesta lenta anterior no pise a una más reciente. Cada pulsación que llega a la API es una petición contra tu cuota diaria, así que el debounce es tanto un control de costes como un detalle de UX.

Cuando el usuario elige una fila, llama a la API de base de datos de alimentos con el id para obtener el registro completo, o a la API de nutrición si solo necesitas la tabla de nutrientes por 100 g. Una búsqueda más una petición de detalle sale más barato que traer registros completos para cada sugerencia.

La respuesta de búsqueda capturada no lleva cabecera Cache-Control, a diferencia de los registros de alimentos, que se pueden cachear durante 300 segundos. Cachea tú los resultados de búsqueda, con clave en la combinación exacta de q, lang, limit y offset; los mismos prefijos cortos se repiten constantemente en un cuadro de escritura predictiva. X-RateLimit-Second-Remaining indica cuánta ráfaga queda y, ante un 429, la cabecera Retry-After indica cuántos segundos esperar.