Event Data API para developers

Contrato exportable

Si vas a integrar en serio, no dependas solo de esta página. Descarga el contrato OpenAPI y versiona ese artefacto junto con tu cliente, tu SDK interno o tus tests de integración.

Artefactos públicos: https://api.parchar.ai/api/public/data-api/openapi.json y https://api.parchar.ai/api/public/data-api/postman.json

SDK TypeScript de referencia

También mantenemos un cliente TypeScript alineado con el mismo contrato: @parchar/data-api-client. Hoy vive dentro del repo y sirve como wrapper ligero sobre fetch, no como una especificación paralela.

import { createParcharDataApiClient } from "@parchar/data-api-client";

const client = createParcharDataApiClient({
  apiKey: process.env.PARCHAR_API_KEY!,
});

const response = await client.listEvents({
  country_code: "CO",
  city: "bogota",
  date_from: "2026-04-18",
  limit: 20,
});

console.log(response.data[0]?.quality.freshness_status);
console.log(response.rateLimit.remaining_minute);

La regla sigue siendo la misma: el OpenAPI es la fuente de verdad y el SDK se mantiene pegado a ese contrato para no inventar una experiencia distinta de la API real.

Polling incremental y cambios

Cuando tu integración deja de ser exploratoria, el cambio correcto no es “polling más agresivo” sino pasar a `/changes` y a canales de salida. Build abre ese primer carril.

curl -H "X-API-Key: parch_build_live_xxxxx" \
  "https://api.parchar.ai/api/v1/changes?updated_since=2026-04-17T00:00:00Z&limit=100"

El feed de cambios se construye sobre `published_event_changes`, no sobre filas crudas del scraper. Eso significa menos ruido, más trazabilidad y degradación coherente con el serving layer.

Webhooks, exports y surfaces complementarias

Ejemplo en JavaScript

Este primer ejemplo sirve para un backend Node, un worker o un job de sync. Empieza con filtros estructurados y deja que `quality.*` gobierne tus decisiones de ranking o fallback.

const response = await fetch(
  "https://api.parchar.ai/api/v1/events?country_code=CO&city=bogota&date_from=2026-04-18&limit=20",
  {
    headers: { "X-API-Key": process.env.PARCHAR_API_KEY! }
  }
);

if (!response.ok) throw new Error(`Parchar API error: ${response.status}`);
const payload = await response.json();
console.log(payload.data[0]?.quality?.freshness_status);

Ejemplo en Python

Útil para pipelines, agentes o integraciones internas. Si subes a Build o Growth, el siguiente paso correcto es sumar `/changes` y luego webhooks, no bajar el intervalo de polling sin control.

import os
import requests

response = requests.get(
    "https://api.parchar.ai/api/v1/events",
    params={
        "country_code": "CO",
        "city": "bogota",
        "date_from": "2026-04-18",
        "limit": 20,
    },
    headers={"X-API-Key": os.environ["PARCHAR_API_KEY"]},
    timeout=20,
)
response.raise_for_status()
payload = response.json()
print(payload["data"][0]["quality"]["freshness_status"])