Перейти к основному содержимому

Календарь матчей за месяц

Эндпоинт /v2/{sportSlug}/matches/{yearMonth}/calendar возвращает по каждому дню месяца количество турниров и матчей. Подходит для рендеринга календаря-сетки без загрузки самих матчей.

yearMonth — строка вида YYYY-MM (например, 2026-05).

Запрос​

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.api-sport.ru/v2/football/matches/2026-05/calendar"

Ответ​

{
  "month": "2026-05",
  "totalDays": 31,
  "days": [
    { "date": "2026-05-01", "totalTournaments": 12, "totalMatches": 24 },
    { "date": "2026-05-02", "totalTournaments": 9,  "totalMatches": 18 },
    { "date": "2026-05-03", "totalTournaments": 0,  "totalMatches": 0 }
    /* ...всего totalDays элементов, включая пустые дни */
  ]
}

Дни без матчей возвращаются как { totalTournaments: 0, totalMatches: 0 } — массив всегда покрывает весь месяц.

Загрузка матчей на конкретную дату​

Когда пользователь выбрал день — отдельный запрос на список матчей с фильтром date=:

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.api-sport.ru/v2/football/matches?date=2026-05-15&page_size=100"

React-пример (псевдокод)​

function MatchCalendar({ sport, yearMonth }: { sport: string; yearMonth: string }) {
  const [calendar, setCalendar] = useState<CalendarResponse | null>(null);
  const [matches, setMatches] = useState<Match[]>([]);
  const [selectedDate, setSelectedDate] = useState<string | null>(null);

  useEffect(() => {
    fetch(`https://api.api-sport.ru/v2/${sport}/matches/${yearMonth}/calendar`, {
      headers: { Authorization: API_KEY },
    })
      .then((r) => r.json())
      .then(setCalendar);
  }, [sport, yearMonth]);

  useEffect(() => {
    if (!selectedDate) return;
    fetch(
      `https://api.api-sport.ru/v2/${sport}/matches?date=${selectedDate}&page_size=100`,
      { headers: { Authorization: API_KEY } }
    )
      .then((r) => r.json())
      .then(({ matches }) => setMatches(matches));
  }, [selectedDate, sport]);

  return (
    <div>
      <CalendarGrid days={calendar?.days ?? []} onSelect={setSelectedDate} />
      <MatchList matches={matches} />
    </div>
  );
}

Полезные дополнительные фильтры​

Эндпоинт /calendar принимает те же фильтры, что и /matches:

  • tournament_id=1,2,3 — оставить только указанные турниры.
  • category_ids=1,2 — оставить только указанные категории (страны).
  • team_id=12345 — только матчи с участием этой команды.
  • season_id=... — конкретный сезон.
  • exclude_amateur=true — исключить amateur/editor матчи.

Кэширование​

  • Календарь прошлых месяцев — не меняется. Кэшируйте навсегда.
  • Текущий и будущие месяцы — могут пополняться. Кэшируйте на 1–6 часов.
Последнее обновление