Referencia de API · v1

Documentación.

Todos los endpoints públicos, autenticación, rate limits y ejemplos de código.

Autenticación

La API key es opcional. Sin key tienes 60 requests/hora por IP — perfecto para probar. Con una key gratis de troostlog.com/desarrolladores subes el límite a 100/hora y obtienes tracking de uso.

# Sin key (60 req/hora por IP)
curl https://troostlog.com/api/v1/corredores

# Con x-api-key (100 req/hora del key)
curl https://troostlog.com/api/v1/corredores \
  -H "x-api-key: troost_..."

# O con Authorization: Bearer
curl https://troostlog.com/api/v1/corredores \
  -H "Authorization: Bearer troost_..."

Rate limits

Plan free (sin key): 60 requests/hora por IP. Plan free (con key): 100/hora. Los headers x-ratelimit-remaining y x-ratelimit-limit en la respuesta te dicen cuántas te quedan.

Errores

{
  "error":   "rate_limit_exceeded_ip",
  "message": "rate_limit_exceeded_ip"
}

401 invalid_api_key · mandaste key pero no existe
401 key_inactive | key_expired · key revocada/expirada
429 rate_limit_exceeded · excediste el límite del key
429 rate_limit_exceeded_ip · pasaste de 60/h por IP — crea una key gratis para subir el límite
404 not_found | corredor_not_found
400 bad_periodo | bad_corredor

Endpoints

GET/api/v1/corredores

Query params

Nombre	Tipo	Valores	Default
limit	integer	1–500	100
ordenar	string	fletes \| score \| confianza	fletes

Request

curl https://troostlog.com/api/v1/corredores?ordenar=confianza&limit=10 \
  -H "x-api-key: troost_..."

Response (truncado)

{
  "corredores": [
    { "corredor": "queretaro_cdmx", "score_confianza": 87, "total_fletes": 1240, "incidentes": 3, "pct_a_tiempo": 92.1 }
  ],
  "total": 87,
  "orden": "confianza",
  "periodo": "last_90_days"
}

GET/api/v1/incidentes

Query params

Nombre	Tipo	Valores	Default
desde	YYYY-MM-DD	—	30d ago
hasta	YYYY-MM-DD	—	today
tipo	string	robo, asalto, accidente, ...	all
corredor	string	snake_case	all
limit	integer	1–1000	100

Request

curl https://troostlog.com/api/v1/incidentes?tipo=robo&desde=2026-04-01 \
  -H "x-api-key: troost_..."

Response (truncado)

{
  "incidentes": [
    {
      "id": "...",
      "fecha": "2026-04-15",
      "corredor": "queretaro_cdmx",
      "ubicacion_aprox": { "lat": 20.4, "lng": -100.1 },
      "tipo_incidente": "robo",
      "severidad": "mayor",
      "monto_aprox_rango": "100k_500k"
    }
  ],
  "total": 23
}

GET/api/v1/metricas/mes/[YYYY-MM]

Request

curl https://troostlog.com/api/v1/metricas/mes/2026-04 \
  -H "x-api-key: troost_..."

Response (truncado)

{
  "periodo": { "anio": 2026, "mes": 4, ... },
  "hero": { "total_fletes": 47280, "gmv": 2418000000, "total_incidentes": 142, ... },
  "comparativa": { "fletes_vs_mes_anterior_pct": 7.2, ... },
  "top_corredores_volumen": [ ... ],
  "top_corredores_peligrosos": [ ... ],
  "mercancias_vulnerables": [ ... ],
  "tendencia_6m": [ ... ]
}

GET/api/v1/score-corredor/[corredor]

Request

curl https://troostlog.com/api/v1/score-corredor/queretaro_cdmx \
  -H "x-api-key: troost_..."

Response (truncado)

{
  "corredor": "queretaro_cdmx",
  "score_confianza": 87,
  "metricas": {
    "score_riesgo_90d": 28.5,
    "incidentes_90d": 3,
    "precio_promedio_km": 28.12,
    "pct_a_tiempo": 92.1,
    "total_fletes_90d": 1240,
    "tendencia_precios": [ ... ],
    "top_mercancias": [ ... ]
  }
}

Privacidad y ética

Todos los datos están anonimizados antes de ser publicados. Las coordenadas se redondean a 0.1° (~11 km de imprecisión). Los montos se reportan en rangos (menos de 100k, 100k–500k, etc). Un corredor solo aparece si al menos 2 empresas distintas lo operaron en el periodo (k-anonymity ≥2). Nunca se devuelven identificadores de empresa, operador ni flete.