API

Cherchez une ville puis demandez le paquet horaire complet.

L API SunriseTime sert d abord a decouvrir les slugs de ville, puis a recuperer les donnees soleil, lune et priere dans une reponse structuree. Le catalogue actuel couvre 500 villes indexees.

Mode d acces

Beta publique
Aucune cle API requise pour le moment
Adaptee aux integrations en lecture seule et aux outils legers
Objectif actuel : 100 requetes par IP et par jour

Bases du produit

Versionnee sous /api/v1/
Chaque reponse JSON contient un bloc meta
Le CORS pour les navigateurs tiers reste limite
Les reponses JSON envoient X-Robots-Tag: noindex

Politique de cache

/api/v1/times : 15 minutes
/api/v1/cities : 60 minutes
/api/v1/openapi.json : 60 minutes

Demarrage rapide

Recuperez d abord un slug de ville, puis demandez les horaires avec ce slug.

1. Recuperer le slug de ville

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

2. Recuperer les horaires

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

Endpoints

Ces trois endpoints suffisent pour la plupart des integrations externes.

GET /api/v1/cities Recherchez des villes par nom, slug, pays ou region et obtenez des slugs stables. GET /api/v1/times Recuperez lever, coucher, heure doree, lune et horaires de priere pour une ville et une date. GET /api/v1/openapi.json Lisez le document OpenAPI pour des clients generes ou des outils internes.

Parametres

Gardez le flux simple : slug d abord, puis une ville par requete.

`/api/v1/cities`

Parametre	Obligatoire	Notes
`query`	Non	Ville, slug, pays ou region administrative. Une requete vide renvoie des villes populaires.
`limit`	Non	10 par defaut, 25 maximum.

`/api/v1/times`

Parametre	Obligatoire	Notes
`city`	Oui	Slug stable comme paris, istanbul ou london.
`date`	Non	Date locale optionnelle au format YYYY-MM-DD.

Structure de reponse

Le JSON est groupe par cas d usage pour faciliter la reutilisation.

JSON

meta : version, endpoint, URL de docs, TTL de cache et echo de requete
city : slug, nom, coordonnees, fuseau et metadonnees de population
links : URLs du site et de l API liees a la ville
blocs sun, goldenHour, moon et prayerTimes

Sample response

{
  "meta": {
    "version": "v1",
    "endpoint": "/api/v1/times",
    "cacheTtlSeconds": 900
  },
  "city": {
    "slug": "paris",
    "name": "Paris",
    "timezone": "Europe/Paris"
  },
  "sun": {
    "sunrise": "7:25 AM",
    "sunset": "8:09 PM"
  },
  "moon": {
    "phase": "Waxing Crescent",
    "illumination": 12
  },
  "prayerTimes": {
    "fajr": "5:57 AM",
    "maghrib": "8:10 PM"
  }
}

Exemples d integration

La ligne de commande et le serveur restent les meilleurs usages pour le moment. L acces navigateur tiers doit attendre un CORS plus large.

cURL

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

JavaScript

const cityLookup = await fetch("https://sunrisetime.co/api/v1/cities?query=paris&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);

Modele d erreurs

Les erreurs reviennent en JSON structure, ce qui rend la gestion externe plus fiable.

Code	Statut	Signification
`missing_city`	400	Le parametre city n a pas ete envoye a /api/v1/times.
`invalid_date`	400	La valeur date n etait pas au format YYYY-MM-DD.
`unknown_city`	404	Le slug de ville envoye n existe pas dans l index actuel.
`invalid_limit`	400	La valeur limit envoyee a /api/v1/cities etait invalide.

Etapes suivantes

Utilisez ces liens pour verifier la methode, inspecter les slugs publics ou demander un volume plus eleve.

Methodologie Consultez les hypotheses solaires, lunaires et de priere derriere les blocs de reponse. Index des villes Parcourez le repertoire public si vous voulez verifier les slugs a la main. Contact Besoin d un volume plus eleve ou d un parcours dedie ? Ecrivez a hello@sunrisetime.co.