Consultas y filtros

Aprende a buscar, filtrar, ordenar y paginar los resultados de la API de ImpactU.

Los endpoints de búsqueda (/search/...) comparten una misma forma de consultar. Esta guía te muestra cómo combinar sus parámetros.

Los cuatro bloques de una consulta

Bloque	Parámetro	Para qué sirve
Búsqueda por texto	keywords	Buscar por nombre o título
Paginación	max, page	Recorrer los resultados por partes
Ordenamiento	sort	Definir el orden de los resultados
Filtros	Varía según la entidad	Acotar los resultados

1. Busca por texto

   Usa keywords para buscar por nombre o título.

   GET /search/works?keywords=colombia
   
2. Pagina los resultados

   Usa max (de 1 a 250) y page. La respuesta incluye en meta.count el total de resultados y en meta.cursor.next la URL de la página siguiente.

   GET /search/works?max=20&page=2
   
3. Ordena

   sort usa el formato campo_direccion, donde la dirección es asc o desc.

   GET /search/works?sort=year_desc
   
4. Filtra

   Cada entidad tiene sus propios filtros. Para enviar varios valores, sepáralos con coma.

   GET /search/works?years=2020,2026&status=diamond,gold
   

Campos de ordenamiento por entidad

Endpoint	Campos de sort
/search/person	citations, products, h, h5
/search/works	citations, alphabetical, year
/search/affiliations/{tipo}	citations, products, h, h5
/search/sources	citations, products, alphabetical
/search/patents	alphabetical
/search/projects	alphabetical
/search/geo/{tipo}	alphabetical

El valor de sort debe tener exactamente un guion bajo (por ejemplo, products_desc). Valores como products_count_desc o year:desc producen un error 400.

Si no envías max, page ni sort, se aplican max=10, page=1 y sort=citations_desc. Los listados de patentes y proyectos solo se ordenan por alphabetical, así que envía sort=alphabetical_asc o sort=alphabetical_desc en ellos.

Filtros por entidad

Endpoint	Filtros
/search/works	years, product_types, status, topics, countries, authors_count, authors_ranking, groups_ranking, institutions_type
/search/affiliations/{tipo}	states, cities, groups_ranking
/search/sources	source_types, scimago_quartiles, apc_range, status, publication_time, license_type, topics
/search/person, /search/patents, /search/projects, /search/geo/{tipo}	Sin filtros

Descubre los valores válidos

Productos, afiliaciones y fuentes tienen un endpoint que devuelve las opciones disponibles de cada filtro, con la cantidad de resultados de cada una:

• GET /search/works/filters
• GET /search/affiliations/{affiliation_type}/filters
• GET /search/sources/filters

Estos endpoints aceptan los mismos filtros que el listado. Si ya aplicaste un filtro, solo devuelven las opciones que existen dentro de ese resultado. El value de cada opción es el que debes enviar en el filtro.

Formatos especiales

Rangos: years, apc_range y publication_time

Se envían como mínimo y máximo separados por coma.

years=2020,2026

Cantidad de autores: authors_count

Acepta cuatro formatos:

Valor	Significado
5	Exactamente 5 autores
5-	5 o más autores
-5	Hasta 5 autores
5-8	De 5 a 8 autores

Tópicos y tipos de producto

Usa el value devuelto por el endpoint de filtros. En topics es la URL de OpenAlex (por ejemplo, https://openalex.org/T14483) y en product_types lleva el prefijo de la fuente (por ejemplo, impactu_Artículo de revista).

Ejemplo completo

Productos publicados entre 2020 y 2026, de acceso abierto, con hasta 10 autores, ordenados por año descendente, de 20 en 20:

cURL

curl --get "https://api.dev.impactu.colav.co/search/works" \
  --data-urlencode "years=2020,2026" \
  --data-urlencode "status=open" \
  --data-urlencode "authors_count=-10" \
  --data-urlencode "sort=year_desc" \
  --data-urlencode "max=20" \
  --data-urlencode "page=1" \
  --header "Accept: application/json"

Recorrer todas las páginas

Calcula el número de páginas con meta.count y recórrelas una por una:

import math
import requests

URL = "https://api.dev.impactu.colav.co/search/sources"
MAX = 250
params = {"max": MAX, "page": 1, "sort": "products_desc", "status": "open"}

first = requests.get(URL, params=params, timeout=60).json()
total_pages = math.ceil(first["meta"]["count"] / MAX)
items = first["data"]

for page in range(2, total_pages + 1):
    params["page"] = page
    items += requests.get(URL, params=params, timeout=60).json()["data"]

print(len(items))

Errores comunes

Los errores se devuelven con código 400 y un mensaje en error.

Causa	Ejemplo
authors_count inválido	authors_count=0, authors_count=8-5
sort con formato incorrecto	sort=year:desc
geo_type distinto de city o state	/search/geo/country
max fuera de rango	max=500