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
https://api.responsegrid.appLa 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.
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.
- Elige una emergencia: lista las activas y quédate con su id (o resuelve el slug).
- Pide sus puntos públicos paginando (hasta 100 por página).
- Pinta un marcador por cada punto y coloréalo según su estado.
curl https://api.responsegrid.app/emergencies
curl "https://api.responsegrid.app/emergencies/{emergencyId}/public/resources?limit=100"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
});
}Listar emergencias
/emergenciesDevuelve las emergencias activas. Úsalo para obtener el emergencyId que necesitan el resto de llamadas.
[
{
"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.
/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 https://api.responsegrid.app/emergencies/by-slug/venezuelaPuntos logísticos (lectura)
/emergencies/{emergencyId}/public/resourcesEl 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ámetro | Descripción |
|---|---|
page | Página, empezando en 1. |
limit | Elementos por página. Por defecto 50, máximo 100. |
category | Filtra por categoría que el punto acepta (slug, p. ej. water, food). |
country | Filtra por país tal y como lo guarda el origen (p. ej. VE o «Venezuela»). |
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.
{
"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.
| Campo | Tipo | Descripción |
|---|---|---|
name | string | Nombre del centro o punto. |
type | enum | Tipo de punto (ver «Tipo de punto»). |
stage | enum | Rol en la cadena: origen, intermedio o destino. |
location | { address, latitude, longitude } | Dirección y coordenadas (latitude, longitude). |
publicStatus | enum | Estado operativo: el semáforo (active, saturated, paused, closed). |
verificationLevel | enum | Nivel de confianza: verified u official. |
accepts | string[] | Categorías que el punto acepta (p. ej. ["water","food"]). |
contact | string | null | Teléfono o contacto del punto. Puede ser null. |
schedule | string | null | Horario de atención. Puede ser null. |
manager | string | null | Persona responsable. Puede ser null. |
sourceName | string | null | Origen del dato cuando procede de una fuente externa. Puede ser null. |
externalUpdatedAt | string | null | Fecha (ISO 8601) de la última actualización en el origen. Puede ser null. |
country | string | null | País tal y como lo guarda el origen (a menudo el nombre completo). Puede ser null. |
city | string | null | Ciudad. Puede ser null. |
id | string (uuid) | Identificador único del punto. |
ownerOrganizationId | string | null | Organización propietaria del punto. Puede ser null. |
Facetas (para construir filtros)
/emergencies/{emergencyId}/public/resources/facetsSi 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.
{
"byCategory": { "water": 12, "food": 9, "medical": 4 },
"byCountry": { "VE": 18, "CO": 7 },
"total": 25
}Necesidades (lectura)
/emergencies/{emergencyId}/public/needsDevuelve 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 "https://api.responsegrid.app/emergencies/{emergencyId}/public/needs?priority=high"[
{
"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.
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:
| Valor | Descripción |
|---|---|
active | Operativo y aceptando ayuda. |
saturated | Desbordado: mejor no llevar más material ahora. |
paused | En pausa temporal. |
closed | Cerrado. |
Nivel de confianza
El campo verificationLevel (la API pública solo devuelve los dos últimos):
| Valor | Descripción |
|---|---|
unverified | En cola, sin validar (no aparece en la API pública). |
verified | Validado por la coordinación local. |
official | Publicado por una organización acreditada. |
Tipo de punto
El campo type:
collection_pointdelivery_pointcollection_and_deliverywarehousetransportsuppliervenueRol en la cadena
El campo stage: origin (origen), intermediate (intermedio) o destination (destino).
originintermediatedestinationCategorías
Usadas en accepts (puntos), en items[].category (necesidades) y como filtro category.
hygienewaterfoodclothingsheltermedicaltoolsothermedicinesmedical_equipmentmedical_suppliesmedical_personnelPrioridad
El campo priority de las necesidades: low, medium, high, urgent.
lowmediumhighurgentAportar 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).
Primero, consigue un token:
/auth/registercurl -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
/emergencies/{emergencyId}/needsAuthorization: BearerMínimo: title, priority, location e items (al menos uno). Devuelve el id creado.
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)
/emergencies/{emergencyId}/offersAuthorization: BearerUna 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 -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
/emergencies/{emergencyId}/resourcesAuthorization: BearerMínimo: type, stage, name y location. Opcional: accepts, contact, schedule, country, city. Nace sin verificar hasta que coordinación lo publica.
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:
ResponseGrid by Global Emergency — CC BY-SA 4.0 — https://responsegrid.app<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>Referencia y enlaces
Referencia interactiva (Swagger)
Explora y prueba todos los endpoints en vivo.
https://api.responsegrid.app/docsEspecificación OpenAPI
El JSON de OpenAPI, para generar clientes o importar en tus herramientas.
https://api.responsegrid.app/docs-jsonCliente TypeScript tipado
Paquete @reliefhub/api-client (openapi-fetch): tipos y autocompletado para consumir la API desde TypeScript.
@reliefhub/api-client¿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