API para desarrolladores

Construye sobre la fuente de la verdad

La API pública de ResponseGrid te da acceso, sin login, a los puntos logísticos verificados y a las necesidades validadas de cada emergencia. Está pensada para que cualquier proyecto —un mapa, un buscador, un panel— consuma datos oficiales y en tiempo real en vez de duplicarlos.

Visión general

ResponseGrid coordina la ayuda durante una catástrofe: publica los puntos logísticos verificados, recoge y valida las necesidades, y lo mantiene todo en un mapa en tiempo real. Esta API expone esa misma información para que la integres en tu propio producto.

El objetivo es que no haya cien mapas distintos contradiciéndose: tú consumes los datos verificados y nosotros somos la fuente de la verdad. Solo se publica lo que la coordinación local ha validado, así que lo que lees ya está depurado.

URL base

Base URL
https://api.responsegrid.app

La URL base depende del despliegue; usa la que te indiquemos para producción. Los ejemplos de esta página usan esta instancia.

Formato
JSON sobre HTTPS. Todas las respuestas son UTF-8.
Lectura
Pública, sin autenticación. Todos los GET de esta sección son anónimos.
Escritura
Requiere un token JWT (Bearer). Ver «Aportar datos».
Ámbito
Todo cuelga de una emergencia, identificada por su UUID o su slug.
Licencia de datos
CC BY-SA 4.0 — atribución obligatoria + compartir igual.

Conceptos

Cuatro ideas bastan para consumir la API con criterio:

Emergencia

El contenedor de todo. Tiene un nombre, un slug legible (p. ej. «venezuela»), país y estado (activa / en pausa / cerrada). Cada punto y cada necesidad pertenece a una emergencia.

Punto logístico

Un sitio físico: punto de recogida o de entrega, almacén, transporte, proveedor o local. Trae nombre, ubicación (dirección + coordenadas), qué acepta, contacto, horario y un semáforo de estado operativo.

Necesidad

Lo que se pide en el terreno (agua, alimentos, material sanitario, personal…), con prioridad e ítems. Públicamente solo se exponen las necesidades validadas por coordinación.

Niveles de confianza

Cada punto lleva un nivel: en cola (aún no fiable), verificado (validado por la coordinación local) u oficial (organización acreditada). La API pública solo devuelve puntos verificados u oficiales: por eso es fuente de la verdad.

Autenticación

Hay tres esquemas. Identifica cuál acepta cada endpoint antes de integrar.

Lectura — sin token

Los endpoints de consulta (emergencias, puntos públicos, necesidades públicas) no requieren credenciales. Si solo quieres mostrar datos, no necesitas autenticarte.

Escritura — token Bearer

Para crear necesidades, ofertas o puntos necesitas una cuenta de usuario. Regístrate o haz login y recibirás un accessToken (JWT) que envías en la cabecera Authorization: Bearer <token>.

Cuentas de servicio — cabecera x-api-key

Para integraciones máquina-a-máquina existen las cuentas de servicio. Un administrador crea la cuenta y emite una clave (rh_live_…) que viaja en la cabecera x-api-key (no como Bearer). Con ella el llamante puede introspeccionar su identidad y permisos: GET /service-accounts/me.

Una clave x-api-key autentica al principal de la cuenta de servicio, pero no sustituye al Bearer en los endpoints de escritura documentados (necesidades, ofertas y puntos): estos esperan un JWT de cuenta de usuario y responden 401 ante una API key. Una cuenta de servicio solo puede actuar dentro de sus grants (por defecto, ninguno), así que sin permisos explícitos su clave no habilita escritura.

Inicio rápido: un mapa de puntos

El caso más común: pintar en un mapa dónde se puede recoger o entregar ayuda. Tres llamadas y listo.

  1. Elige una emergencia: lista las activas y quédate con su id (o resuelve el slug).
  2. Pide sus puntos públicos paginando (hasta 100 por página).
  3. Pinta un marcador por cada punto y coloréalo según su estado.
cURL
curl https://api.responsegrid.app/emergencies

curl "https://api.responsegrid.app/emergencies/{emergencyId}/public/resources?limit=100"
JavaScript
const base = "https://api.responsegrid.app";

// 1) pick an emergency
const list = await fetch(base + "/emergencies").then((r) => r.json());
const id = list[0].id;

// 2) fetch its public points and plot them
const url = base + "/emergencies/" + id + "/public/resources?limit=100";
const { items } = await fetch(url).then((r) => r.json());

for (const p of items) {
  addMarker({
    title: p.name,
    lat: p.location.latitude,
    lng: p.location.longitude,
    status: p.publicStatus, // active | saturated | paused | closed
  });
}
Consume la API desde tu backend (servidor a servidor). Las peticiones desde el navegador de otro dominio están sujetas a la lista CORS de la API; si tu app es solo-cliente, haz de proxy desde tu servidor.

Listar emergencias

GET/emergencies

Devuelve las emergencias activas. Úsalo para obtener el emergencyId que necesitan el resto de llamadas.

JSON
[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Emergencia sísmica — Venezuela",
    "slug": "venezuela",
    "country": "VE",
    "status": "active",
    "announcement": "El puente de acceso norte está cortado.",
    "dontBringList": ["ropa usada", "medicamentos caducados"],
    "updatedAt": "2026-06-25T10:00:00.000Z"
  }
]

Cada emergencia incluye id, name, slug, country, status, announcement (comunicado oficial o null), dontBringList (qué NO llevar) y updatedAt.

GET/emergencies/by-slug/{slug}

Si ya conoces el slug (lo ves en la URL pública, p. ej. /e/venezuela), puedes resolver la emergencia directamente:

cURL
curl https://api.responsegrid.app/emergencies/by-slug/venezuela

Puntos logísticos (lectura)

GET/emergencies/{emergencyId}/public/resources

El endpoint principal. Devuelve, paginados, los puntos publicados de una emergencia: solo los verificados u oficiales y visibles. Es lo que pintarías en un mapa.

Parámetros de consulta

ParámetroDescripción
pagePágina, empezando en 1.
limitElementos por página. Por defecto 50, máximo 100.
categoryFiltra por categoría que el punto acepta (slug, p. ej. water, food).
countryFiltra por país tal y como lo guarda el origen (p. ej. VE o «Venezuela»).
cURL
curl "https://api.responsegrid.app/emergencies/{emergencyId}/public/resources?category=water&limit=100&page=1"

Respuesta

Un objeto paginado: items (los puntos), total, page y limit.

JSON
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "collection_point",
      "stage": "destination",
      "name": "Cruz Roja — Centro de acopio",
      "description": "Acopio de agua y alimentos no perecederos",
      "location": {
        "address": "Calle Mayor 1, Valencia",
        "latitude": 39.4699,
        "longitude": -0.3763
      },
      "verificationLevel": "official",
      "publicStatus": "active",
      "accepts": ["water", "food"],
      "contact": "+34 600 000 000",
      "schedule": "Lun-Vie 08-18",
      "manager": "Juan Pérez",
      "sourceName": "acopiove.org",
      "externalUpdatedAt": "2026-06-27T00:00:00.000Z",
      "country": "España",
      "city": "Valencia",
      "ownerOrganizationId": null
    }
  ],
  "total": 128,
  "page": 1,
  "limit": 100
}

Campos públicos de un punto

La información pública es mínima pero suficiente para ubicar y decidir: nombre, dónde está, qué acepta y en qué estado opera.

CampoTipoDescripción
namestringNombre del centro o punto.
typeenumTipo de punto (ver «Tipo de punto»).
stageenumRol en la cadena: origen, intermedio o destino.
location{ address, latitude, longitude }Dirección y coordenadas (latitude, longitude).
publicStatusenumEstado operativo: el semáforo (active, saturated, paused, closed).
verificationLevelenumNivel de confianza: verified u official.
acceptsstring[]Categorías que el punto acepta (p. ej. ["water","food"]).
contactstring | nullTeléfono o contacto del punto. Puede ser null.
schedulestring | nullHorario de atención. Puede ser null.
managerstring | nullPersona responsable. Puede ser null.
sourceNamestring | nullOrigen del dato cuando procede de una fuente externa. Puede ser null.
externalUpdatedAtstring | nullFecha (ISO 8601) de la última actualización en el origen. Puede ser null.
countrystring | nullPaís tal y como lo guarda el origen (a menudo el nombre completo). Puede ser null.
citystring | nullCiudad. Puede ser null.
idstring (uuid)Identificador único del punto.
ownerOrganizationIdstring | nullOrganización propietaria del punto. Puede ser null.

Facetas (para construir filtros)

GET/emergencies/{emergencyId}/public/resources/facets

Si necesitas montar filtros en tu interfaz, este endpoint te da los recuentos por categoría y por país de los puntos visibles, sin tener que descargarlos todos.

JSON
{
  "byCategory": { "water": 12, "food": 9, "medical": 4 },
  "byCountry": { "VE": 18, "CO": 7 },
  "total": 25
}

Necesidades (lectura)

GET/emergencies/{emergencyId}/public/needs

Devuelve las necesidades validadas de una emergencia. Útil para mostrar qué hace falta y dónde. Acepta filtros por categoría (category) y prioridad (priority).

cURL
curl "https://api.responsegrid.app/emergencies/{emergencyId}/public/needs?priority=high"
JSON
[
  {
    "id": "9c2f...",
    "title": "Agua para 50 familias",
    "description": null,
    "priority": "high",
    "status": "validated",
    "location": {
      "address": "Caracas",
      "latitude": 10.49,
      "longitude": -66.90
    },
    "locationSensitivity": "approximate",
    "items": [
      { "name": "Agua", "quantity": 100, "unit": "litros", "category": "water" }
    ],
    "createdAt": "2026-06-27T09:00:00.000Z",
    "expiresAt": "2026-06-29T09:00:00.000Z",
    "lastVerifiedAt": "2026-06-27T10:00:00.000Z"
  }
]

Cada necesidad incluye id, title, description, location, locationSensitivity, priority, items (con name, quantity, unit y category), status, createdAt, expiresAt y lastVerifiedAt.

Privacidad: algunas necesidades exponen coordenadas aproximadas (locationSensitivity: "approximate") para no revelar el domicilio de quien pide. No intentes desofuscarlas; trátalas como orientativas.

Estados y categorías

Valores que verás en las respuestas. Muéstralos a tus usuarios en lugar de inventar los tuyos: así tu app habla el mismo idioma que el resto del ecosistema.

Estado operativo (semáforo)

El campo publicStatus de cada punto:

ValorDescripción
activeOperativo y aceptando ayuda.
saturatedDesbordado: mejor no llevar más material ahora.
pausedEn pausa temporal.
closedCerrado.

Nivel de confianza

El campo verificationLevel (la API pública solo devuelve los dos últimos):

ValorDescripción
unverifiedEn cola, sin validar (no aparece en la API pública).
verifiedValidado por la coordinación local.
officialPublicado por una organización acreditada.

Tipo de punto

El campo type:

collection_pointdelivery_pointcollection_and_deliverywarehousetransportsuppliervenue

Rol en la cadena

El campo stage: origin (origen), intermediate (intermedio) o destination (destino).

originintermediatedestination

Categorías

Usadas en accepts (puntos), en items[].category (necesidades) y como filtro category.

hygienewaterfoodclothingsheltermedicaltoolsothermedicinesmedical_equipmentmedical_suppliesmedical_personnel

Prioridad

El campo priority de las necesidades: low, medium, high, urgent.

lowmediumhighurgent

Aportar datos (con token)

Además de leer, puedes alimentar la plataforma desde tu integración: dar de alta necesidades, ofertas de material (entregas) o puntos logísticos. Estas operaciones requieren un token (ver Autenticación).

Importante: lo que envías no se publica al instante. Las necesidades nacen como «pendientes» y los puntos como «sin verificar»; la coordinación local los valida antes de que aparezcan en los endpoints públicos. Es lo que mantiene la calidad de la fuente.

Primero, consigue un token:

POST/auth/register
cURL
curl -X POST https://api.responsegrid.app/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@ong.org","password":"supersecret","name":"Mi ONG"}'

# → { "accessToken": "eyJhbGciOi..." }

Crear una necesidad

POST/emergencies/{emergencyId}/needsAuthorization: Bearer

Mínimo: title, priority, location e items (al menos uno). Devuelve el id creado.

cURL
curl -X POST https://api.responsegrid.app/emergencies/{emergencyId}/needs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Agua para 50 familias",
    "priority": "high",
    "location": { "address": "Caracas", "latitude": 10.49, "longitude": -66.90 },
    "items": [{ "name": "Agua", "quantity": 100, "unit": "litros", "category": "water" }]
  }'

Ofrecer material (entrega)

POST/emergencies/{emergencyId}/offersAuthorization: Bearer

Una donación, general o dirigida a una necesidad concreta (targetNeedId). Mínimo: category, description, quantity y location. Si la emergencia no acepta altas (en pausa/cerrada) responde 409.

cURL
curl -X POST https://api.responsegrid.app/emergencies/{emergencyId}/offers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "food",
    "description": "Arroz 25kg",
    "quantity": 50,
    "unit": "sacos",
    "location": { "address": "Valencia", "latitude": 39.47, "longitude": -0.38 }
  }'

Registrar un punto logístico

POST/emergencies/{emergencyId}/resourcesAuthorization: Bearer

Mínimo: type, stage, name y location. Opcional: accepts, contact, schedule, country, city. Nace sin verificar hasta que coordinación lo publica.

cURL
curl -X POST https://api.responsegrid.app/emergencies/{emergencyId}/resources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "collection_point",
    "stage": "destination",
    "name": "Punto de acopio barrio Norte",
    "location": { "address": "Av. Norte 12", "latitude": 10.50, "longitude": -66.91 },
    "accepts": ["water", "food"]
  }'

Buenas prácticas

Cachea y consulta con cabeza

No martillees la API: pagina, cachea las respuestas y refresca cada pocos minutos. Usa updatedAt, lastVerifiedAt y externalUpdatedAt para saber qué tan fresco es un dato.

Cita la fuente (obligatorio)

No es solo cortesía: la licencia de los datos (CC BY-SA 4.0) te obliga a atribuir a ResponseGrid / Global Emergency y a enlazar de vuelta. Tienes el texto listo para pegar en «Licencia y atribución».

Respeta los niveles de confianza

Muestra a tus usuarios el verificationLevel y el publicStatus. Un punto «oficial y operativo» no es lo mismo que uno «verificado y saturado»: esa señal es justo el valor que aportamos.

Cuida la privacidad

Trata las ubicaciones aproximadas como tales y no cruces datos para reidentificar a personas. La ayuda va antes que el dato bonito.

Llama desde tu servidor

Los GET públicos son anónimos, pero la API restringe el CORS de navegador a orígenes permitidos. Consume servidor a servidor o haz de proxy desde tu backend.

Licencia y atribución

Los datos que devuelve la API se publican bajo Creative Commons Reconocimiento-CompartirIgual 4.0 (CC BY-SA 4.0). Puedes usarlos, redistribuirlos y adaptarlos —incluso con fines comerciales— siempre que cumplas dos condiciones. (Es la licencia de los datos; el código del proyecto tiene su propia licencia.)

Atribución obligatoria

Da crédito a ResponseGrid / Global Emergency, indica la licencia y enlaza de vuelta a la fuente. El crédito debe estar visible allá donde muestres los datos.

Compartir igual

Si mezclas, transformas o construyes una base de datos a partir de estos datos y la distribuyes, debes publicarla bajo esta misma licencia, CC BY-SA 4.0.

Texto de atribución listo para pegar:

TXT
ResponseGrid by Global Emergency — CC BY-SA 4.0 — https://responsegrid.app
HTML
<a href="https://responsegrid.app">ResponseGrid</a> by <a href="https://globalemergency.online">Global Emergency</a>, licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>
Texto legal completo de la licencia

¿Construyes algo con esto?

Empieza por las emergencias activas y trae sus puntos públicos. Cítanos como fuente y enlaza de vuelta.

Ver emergencias activas