Documentación
Consume el archivo desde tu aplicación.
La API pública de Grafpin devuelve las piezas ya aprobadas del archivo —título, coordenadas, ciudad y foto— en JSON. Es de solo lectura: no publica, no modifica y no expone datos de las personas que documentan.
URL base
https://api.grafpin.com/v1
La clave es de servidor, nunca del navegador
Una API key identifica y factura a su dueño. Si viaja en el JavaScript de una web o dentro de una app móvil, cualquiera puede extraerla y gastar tu cuota. Llama a la API desde tu backend y guarda la clave en una variable de entorno. Por eso mismo la API no habilita CORS para terceros: que una llamada desde el navegador falle es el comportamiento correcto, no un error.
01 · Empezar
Empezar
Tres pasos, sin trámite previo.
- 01
Crea tu cuenta en grafpin.com
La misma cuenta con la que se documenta el archivo. No hace falta subir nada.
- 02
Genera una clave en /api-keys
Se muestra completa una sola vez, al crearla: guárdala en ese momento. Después solo verás su prefijo para identificarla. Puedes tener hasta 5 claves activas y revocar cualquiera cuando quieras.
- 03
Envíala en la cabecera X-API-Key
En todas las peticiones a /v1/pub. Sin cabecera, o con una clave revocada, la respuesta es 401.
Primera llamada
curl -s https://api.grafpin.com/v1/pub/pieces \
-H "X-API-Key: $GRAFPIN_API_KEY"02 · Endpoints
Endpoints
Dos, ambos GET. Es todo lo que hay.
GET /v1/pub/pieces
Lista de piezas aprobadas, de la más reciente a la más antigua.
- page
- Página, desde 1. Por defecto 1.
- per_page
- Piezas por página, entre 1 y 30. Por defecto 30.
- city
- Coincidencia parcial por ciudad.
- style
- Filtra por estilo.
- sw_lat, sw_lon, ne_lat, ne_lon
- Rectángulo geográfico: esquinas suroeste y noreste. Los cuatro o ninguno.
GET /v1/pub/pieces/{id}
Detalle de una pieza: añade descripción, estado de conservación, estilos, contexto y todas sus fotografías. Una pieza que no esté aprobada devuelve 404, exista o no.
Forma de la respuesta
Todas las respuestas comparten la misma envoltura. Los datos van en data y la paginación en meta.
{
"success": true,
"data": [
{
"id": 1042,
"title": "Muro de la 26",
"latitude": "4.65349200",
"longitude": "-74.08368000",
"city": "Bogotá",
"country": "CO",
"cover_url": "https://api.grafpin.com/v1/media/1042/thumb_400_a1b2.jpg?exp=…&v=1&sig=…",
"is_verified": true,
"created_at": "2026-04-12 18:22:05"
}
],
"message": "",
"errors": [],
"meta": { "page": 1, "per_page": 30, "total": 418 }
}Errores
- 401 Falta la cabecera X-API-Key, o la clave es inválida o fue revocada.
- 404 La pieza no existe o no está aprobada.
- 429 Cuota diaria agotada. Vuelve mañana o sube de plan.
- 503 Indisponibilidad temporal. Reintenta según Retry-After.
03 · Imágenes
Imágenes
Las fotos no se sirven desde una ruta fija: cada URL viene firmada y caduca.
No guardes la URL, guarda el id
Los enlaces de cover_url y photos[].url llevan firma y caducidad (unos minutos). Pasado ese tiempo devuelven 403. Vuelve a pedir la pieza para obtener enlaces nuevos.
Tamaño de vista previa
La API pública entrega la variante reducida (lado mayor de 300 a 400 px), suficiente para listados, mapas y fichas. La alta resolución es solo de la aplicación oficial.
Atribución
Las fotografías son de quienes documentan el archivo. Al mostrarlas, enlaza la pieza en grafpin.com y cita a Grafpin como fuente.
04 · Límites y buen uso
Límites y buen uso
La cuota es diaria y por clave. Las respuestas te dicen cuánto te queda.
1 000 peticiones al día
Es el plan gratuito, el que recibe toda clave nueva. Sin tarjeta ni trámite.
Cabeceras de cuota
Cada respuesta trae X-RateLimit-Limit y X-RateLimit-Remaining. Cuando la cuota se agota llega un 429: trátalo, no lo reintentes en bucle.
Cachea del lado tuyo
El archivo cambia despacio. Guarda los listados un rato en tu propio caché en vez de pedirlos en cada visita —los enlaces de imagen sí hay que refrescarlos.
¿Necesitas más?
Hay planes de mayor cuota, y para proyectos de investigación o sin ánimo de lucro se puede acordar acceso. Escríbenos.
05
¿Dudas, o un uso que no encaja aquí?
Cuéntanos qué quieres construir. Si tu proyecto necesita algo que la API pública no cubre —volúmenes distintos, otro corte de los datos— lo hablamos.