API

Busca una ciudad y despues pide el bloque completo de tiempos.

La API de SunriseTime sirve para descubrir slugs de ciudad y luego pedir datos de sol, luna y oracion en una sola respuesta estructurada. El catalogo actual cubre 500 ciudades indexadas.

Modelo de acceso

Beta publica
Por ahora no requiere API key
Pensada para integraciones de solo lectura y herramientas ligeras
Objetivo actual: 100 solicitudes por IP y por dia

Base del producto

Versionada bajo /api/v1/
Cada respuesta incluye un bloque meta
El CORS para navegadores externos sigue limitado
Las respuestas JSON envian X-Robots-Tag: noindex

Politica de cache

/api/v1/times: ventana de 15 minutos
/api/v1/cities: ventana de 60 minutos
/api/v1/openapi.json: ventana de 60 minutos

Inicio rapido

Primero resuelve el slug de la ciudad y despues pide los tiempos con ese slug.

1. Resolver el slug de ciudad

curl "https://sunrisetime.co/api/v1/cities?query=madrid&limit=3"

2. Consultar los tiempos

curl "https://sunrisetime.co/api/v1/times?city=madrid&date=2026-03-29"

Endpoints

Estas tres rutas cubren la mayoria de integraciones externas.

GET /api/v1/cities Busca ciudades por nombre, slug, pais o region y devuelve slugs estables. GET /api/v1/times Devuelve amanecer, atardecer, hora dorada, luna y horarios de oracion para una ciudad y fecha. GET /api/v1/openapi.json Lee el documento OpenAPI para clientes generados o tooling interno.

Parametros

Mantener el flujo simple ayuda: primero slug, luego una ciudad por solicitud.

`/api/v1/cities`

Parametro	Obligatorio	Notas
`query`	No	Ciudad, slug, pais o region administrativa. Vacio devuelve ciudades populares.
`limit`	No	Por defecto 10, maximo 25.

`/api/v1/times`

Parametro	Obligatorio	Notas
`city`	Si	Slug estable como madrid, istanbul o london.
`date`	No	Fecha local opcional en formato YYYY-MM-DD.

Forma de la respuesta

El JSON esta agrupado por caso de uso para que sea mas facil integrarlo.

JSON

meta: version, endpoint, URL de docs, cache TTL y eco de la consulta
city: slug, nombre, coordenadas, zona horaria y metadatos de poblacion
links: URLs relacionadas del sitio y de la API
bloques sun, goldenHour, moon y prayerTimes

Sample response

{
  "meta": {
    "version": "v1",
    "endpoint": "/api/v1/times",
    "cacheTtlSeconds": 900
  },
  "city": {
    "slug": "madrid",
    "name": "Madrid",
    "timezone": "Europe/Madrid"
  },
  "sun": {
    "sunrise": "7:48 AM",
    "sunset": "8:22 PM"
  },
  "moon": {
    "phase": "Waxing Crescent",
    "illumination": 12
  },
  "prayerTimes": {
    "fajr": "5:58 AM",
    "maghrib": "8:23 PM"
  }
}

Ejemplos de integracion

Ahora mismo funciona mejor desde terminal o servidor. El acceso desde navegadores de terceros debe esperar a un control CORS mas amplio.

cURL

curl "https://sunrisetime.co/api/v1/times?city=madrid&date=2026-03-29"

JavaScript

const cityLookup = await fetch("https://sunrisetime.co/api/v1/cities?query=madrid&limit=1");
const cityResult = await cityLookup.json();
const citySlug = cityResult.cities[0]?.slug;

const timingResponse = await fetch(`https://sunrisetime.co/api/v1/times?city=${citySlug}&date=2026-03-29`
);
const timingData = await timingResponse.json();

console.log(timingData.sun.sunrise, timingData.prayerTimes.maghrib);

Modelo de errores

Los errores devuelven JSON estructurado para que el manejo externo sea mas estable.

Codigo	Estado	Significado
`missing_city`	400	No se envio el parametro city a /api/v1/times.
`invalid_date`	400	El valor de date no estaba en formato YYYY-MM-DD.
`unknown_city`	404	El slug de ciudad enviado no existe en el indice actual.
`invalid_limit`	400	El valor de limit enviado a /api/v1/cities era invalido.

Siguientes pasos

Usa estos enlaces cuando quieras validar el metodo, revisar slugs publicos o pedir mas volumen.

Metodologia Revisa los supuestos solares, lunares y de oracion detras de la respuesta. Indice de ciudades Consulta el directorio publico si quieres verificar slugs manualmente. Contacto ?Necesitas mas volumen o una integracion dedicada? Escribe a hello@sunrisetime.co.