horo.pl

Dla deweloperów i agentów AI

API horo.pl

Publiczne JSON API z horoskopami i policzonymi danymi astronomicznymi. Bez klucza, bez rejestracji. CORS otwarty, limit 60 zapytań na minutę na IP.

Licencja i atrybucja

Treści i dane: CC BY 4.0 - możesz cytować, przetwarzać i pokazywać we własnych aplikacjach, z podaniem źródła i linkiem do horo.pl. Każda odpowiedź zawiera pola source (URL strony, z której pochodzi treść) i license; odpowiedzi błędów niosą pole docs z linkiem do tej dokumentacji. Metodę liczenia danych opisujemy na stronie jak liczymy horoskopy.

Zakresy i cache

  • Horoskopy: archiwum od 2025-07-01 do dziś (+ tomorrow dla daily); daty archiwalne dogenerowują się przy pierwszym zapytaniu.
  • Dane astro (/astro/): od 2024-01-01 do dziś - czysta astronomia, liczona na żądanie.
  • Cache: bieżące okresy max-age=1800, archiwum immutable (treści w bazie są niezmienne), metadane znaków 24 h.
  • "Dziś" liczymy według strefy Europe/Warsaw.

Endpointy

GET /api/v1/today

Wszystkie 12 znaków na dziś - jeden request, komplet danych. Idealne dla agentów AI.

curl https://horo.pl/api/v1/today

GET /api/v1/{znak}/{okres}

Bieżący horoskop znaku. Znak: slug PL (baran) lub klucz EN (aries). Okres: daily, weekly, monthly, yearly (albo dzienny, tygodniowy, miesieczny, roczny).

curl https://horo.pl/api/v1/baran/daily

GET /api/v1/{znak}/{okres}/{data}

Konkretna data: YYYY-MM-DD, today, yesterday albo tomorrow (tylko daily). Daty archiwalne generują się przy pierwszym zapytaniu (lazy-fill).

curl https://horo.pl/api/v1/skorpion/daily/2026-07-01

GET /api/v1/astro/{data}

Same dane astronomiczne dnia (pozycje planet, faza Księżyca, retrogradacje, aspekty) - policzone lokalnie, cytowalne fakty.

curl https://horo.pl/api/v1/astro/today

GET /api/v1/signs

Metadane 12 znaków: nazwy, slugi, symbole, daty, żywioły, planety, linki.

curl https://horo.pl/api/v1/signs

Przykładowa odpowiedź

{
  "sign": { "key": "aries", "name": "Baran", "slug": "baran", "symbol": "♈", ... },
  "period": "daily",
  "date": "2026-07-06",
  "summary": "...",
  "general": "...", "love": "...", "career": "...", "finance": "...", "health": "...",
  "scores": { "love": 7, "career": 8, "health": 7 },
  "lucky": { "number": 19, "color": "złoty" },
  "astro": { "sunSign": {...}, "moon": {...}, "planets": [...], "aspects": [...] },
  "source": "https://horo.pl/baran/",
  "license": "CC BY 4.0 - ..."
}

Błędy

Błędy mają jednolity format: { "error": { "code", "message" }, "docs": "https://horo.pl/api" }

Kody błędów API
StatusKodZnaczenie
400 INVALID_INPUT Zły format daty albo tomorrow dla okresu innego niż daily.
404 NOT_FOUND Nieznany endpoint, znak/okres albo data poza zakresem archiwum.
404 NOT_YET Okres z przyszłości - ten horoskop jeszcze nie nadszedł.
429 RATE_LIMITED Przekroczony limit 60 zapytań na minutę na IP.
503 WRITE_FAILED Generacja chwilowo niedostępna (nagłówek retry-after: 300).

Dla agentów i LLM-ów