API — bgdportal.ru

Обзор API

Основная информация

API bgdportal.ru предоставляет программный доступ к данным городского портала Богдановича. Все эндпоинты работают через протокол HTTP и возвращают данные в формате JSON с кодировкой UTF-8.

Базовый URL

https://bgdportal.ru/api

Протокол

HTTPS / HTTP

Методы

Только GET

Формат ответа

application/json; charset=utf-8

CORS

Access-Control-Allow-Origin: *

Аутентификация

Не требуется (кроме чатов)

Быстрый старт

Пример запроса к API с помощью curl:

curl "https://bgdportal.ru/api/news/latest?limit=3"

JavaScript (fetch):

const res = await fetch('/api/news/latest?limit=3'); const { success, data } = await res.json(); console.log(data); // массив новостей

Формат успешного ответа

Все успешные ответы API содержат поле success: true и данные в поле data.

{
  "success": true,
  "data": { ... }  // объект или массив
}

Аутентификация

Публичные эндпоинты

Большинство API-эндпоинтов полностью публичные и не требуют аутентификации. К ним можно обращаться из любого клиента — браузера, мобильного приложения, серверного скрипта.

/api/search — глобальный поиск
/api/news/* — все эндпоинты новостей
/api/horoscope/{sign} — гороскоп
/api/subcategories/{id} — подкатегории

Защищённые эндпоинты

Эндпоинт /api/chats/unread возвращает данные только для авторизованных пользователей. Аутентификация выполняется через сессионный cookie (PHPSESSID), который устанавливается при входе на сайт. Без активной сессии эндпоинт вернёт count: 0.

Обработка ошибок

Формат ошибки

При ошибке API возвращает соответствующий HTTP-код и JSON-объект с описанием:

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Новость не найдена"
  }
}

Коды ответов

Код	Статус	Описание
200	OK	Успешный запрос, данные в поле `data`
400	Bad Request	Некорректные параметры запроса (напр. невалидная категория)
404	Not Found	Ресурс не найден (новость, знак зодиака и т.д.)
500	Server Error	Внутренняя ошибка сервера

Поиск

1 эндпоинт

GET /api/search

Глобальный поиск по порталу с нечётким совпадением. Ищет по 7 разделам: новости, события (афиша), организации, объявления, вакансии, пользователи и герои. Поддерживает поиск с опечатками и автоматическую коррекцию раскладки клавиатуры (EN→RU).

Параметры запроса

Параметр	Тип	Описание
q *	string	Поисковый запрос (минимум 2 символа). Если короче — возвращается пустой результат
limit	integer	Максимум результатов в каждой группе: 1–5. По умолчанию: 3

Группы результатов

Ключ	Раздел	Что ищет
news	Новости	Заголовок опубликованных новостей, мета — категория
events	Афиша	Название событий, мета — дата + категория
organizations	Организации	Название организаций, мета — категория бизнеса
listings	Объявления	Заголовок объявлений, мета — цена (формат: число ₽ / Бесплатно / Договорная)
vacancies	Вакансии	Название вакансий, мета — компания + зарплата
users	Люди	Имя, фамилия или username, мета — @username
heroes	Наши герои	ФИО героев, мета — воинское звание

Пример запроса

curl "https://bgdportal.ru/api/search?q=парк&limit=2"

Пример ответа

{
  "success": true,
  "data": {
    "results": {
      "news": {
        "label": "Новости",
        "icon": "bi-newspaper",
        "items": [
          {
            "title": "Открытие нового парка в центре",
            "url": "/news/otkrytie-novogo-parka",
            "image": "/uploads/news/park.jpg",
            "meta": "Город"
          }
        ],
        "more_url": "/news?search=парк"
      },
      "events": {
        "label": "Афиша",
        "icon": "bi-calendar-event",
        "items": [
          {
            "title": "Фестиваль в парке",
            "url": "/events/festival-v-parke",
            "image": "/uploads/events/fest.jpg",
            "meta": "15.03.2026 · Фестивали"
          }
        ],
        "more_url": "/events?search=парк"
      }
    },
    "total": 2,
    "query": "парк"
  }
}

Группы включаются в ответ только при наличии совпадений
Каждая группа: label (название), icon (Bootstrap Icon), items[], more_url (ссылка «Ещё»)
total — общее кол-во найденных элементов по всем группам
Поиск автоматически исправляет раскладку: ghj → про
Нечёткий поиск: обрезает окончания для совпадения с опечатками
Ищет только по опубликованным / активным записям

Новости

6 эндпоинтов

GET /api/news

Список опубликованных новостей с пагинацией, фильтрацией по категории и полнотекстовым поиском. Сортировка по дате публикации (новые первыми). Категория валидируется по справочнику — если передана несуществующая, вернётся ошибка 400.

Параметры запроса (Query String)

Параметр	Тип	Описание
page	integer	Номер страницы, ≥ 1. По умолчанию: 1
limit	integer	Элементов на странице: 1–50. По умолчанию: 20
category	string	Фильтр по категории (ключ). Допустимые значения — см. /api/news/categories
search	string	Полнотекстовый поиск по заголовку и содержимому

Примеры запросов

# Все новости (первая страница) curl "https://bgdportal.ru/api/news" # Новости спорта, 2-я страница, по 10 штук curl "https://bgdportal.ru/api/news?category=sport&page=2&limit=10" # Поиск по тексту curl "https://bgdportal.ru/api/news?search=школа"

Пример ответа

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 42,
        "title": "Открытие нового парка в Богдановиче",
        "slug": "otkrytie-novogo-parka",
        "excerpt": "В центре города открылся современный парк...",
        "category": {
          "key": "city",
          "name": "Город"
        },
        "image": "https://bgdportal.ru/uploads/news/park.jpg",
        "is_featured": false,
        "views": 342,
        "published_at": "2026-02-28 10:00:00",
        "url": "https://bgdportal.ru/news/otkrytie-novogo-parka",
        "author": {
          "username": "admin",
          "name": "Иван Петров"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total_items": 45,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  }
}

Структура объекта новости

Поле	Тип	Описание
id	integer	Уникальный идентификатор
title	string	Заголовок
slug	string	URL-идентификатор (транслит)
excerpt	string	Краткое описание
category	object	`key` — ключ категории, `name` — название
image	string\|null	Абсолютный URL изображения или `null`
is_featured	boolean	Важная новость (закреплена)
views	integer	Количество просмотров
published_at	string	Дата публикации `YYYY-MM-DD HH:MM:SS`
url	string	Полный URL страницы новости
author	object	`username`, `name` (ФИО или `null`)
content	string	Только в детальном ответе. HTML-контент
gallery	array	Только в детальном. Массив `{id, url, caption}`

Ошибка (невалидная категория)

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Недопустимая категория"
  }
}

GET /api/news/latest

Быстрый доступ к последним опубликованным новостям без пагинации и фильтрации. Идеально для виджетов, Telegram-ботов и интеграций со сторонними сервисами. Возвращает плоский массив в data.

Параметры запроса

Параметр	Тип	Описание
limit	integer	Количество новостей: 1–10. По умолчанию: 5

Пример запроса

curl "https://bgdportal.ru/api/news/latest?limit=3"

Пример ответа

{
  "success": true,
  "data": [
    {
      "id": 50,
      "title": "Новый маршрут городского транспорта",
      "slug": "novyj-marshrut-transporta",
      "excerpt": "С 1 марта запускается маршрут №15...",
      "category": { "key": "transport", "name": "Транспорт" },
      "image": "https://bgdportal.ru/uploads/news/bus.jpg",
      "is_featured": false,
      "views": 78,
      "published_at": "2026-02-28 16:00:00",
      "url": "https://bgdportal.ru/news/novyj-marshrut-transporta",
      "author": { "username": "admin", "name": "Иван Петров" }
    }
  ]
}

Ответ — массив объектов в data (без pagination)
Структура объекта идентична элементу из /api/news (без content и gallery)

GET /api/news/featured

Важные (featured) новости, отмеченные редакцией. Это закреплённые новости портала с флагом is_featured = true. Сортировка по дате (новые первыми). Возвращает плоский массив.

Параметры запроса

Параметр	Тип	Описание
limit	integer	Количество новостей: 1–10. По умолчанию: 5

Пример запроса

curl "https://bgdportal.ru/api/news/featured?limit=2"

Пример ответа

{
  "success": true,
  "data": [
    {
      "id": 38,
      "title": "Важное объявление о графике работы МФЦ",
      "slug": "grafik-raboty-mfc",
      "excerpt": "В связи с праздничными днями МФЦ меняет график...",
      "category": { "key": "announcements", "name": "Анонсы" },
      "image": "https://bgdportal.ru/uploads/news/mfc.jpg",
      "is_featured": true,
      "views": 1250,
      "published_at": "2026-02-27 09:00:00",
      "url": "https://bgdportal.ru/news/grafik-raboty-mfc",
      "author": { "username": "admin", "name": "Иван Петров" }
    }
  ]
}

GET /api/news/categories

Полный список категорий новостей с ключами, русскими названиями и иконками Bootstrap Icons. Используйте значение key для фильтрации в /api/news?category=.... Порядок категорий фиксирован.

Пример запроса

curl "https://bgdportal.ru/api/news/categories"

Ответ (все 15 категорий)

{
  "success": true,
  "data": [
    { "key": "city",          "name": "Город",             "icon": "building" },
    { "key": "society",       "name": "Общество",          "icon": "people" },
    { "key": "economy",       "name": "Экономика",         "icon": "graph-up-arrow" },
    { "key": "sport",         "name": "Спорт",             "icon": "trophy" },
    { "key": "culture",       "name": "Культура",          "icon": "palette" },
    { "key": "incidents",     "name": "Происшествия",     "icon": "exclamation-triangle" },
    { "key": "politics",      "name": "Политика",          "icon": "bank" },
    { "key": "health",        "name": "Здоровье",          "icon": "heart-pulse" },
    { "key": "updates",       "name": "Обновления",        "icon": "arrow-repeat" },
    { "key": "community",     "name": "Русская община",    "icon": "globe" },
    { "key": "technology",    "name": "Технологии",        "icon": "cpu" },
    { "key": "education",     "name": "Образование",       "icon": "mortarboard" },
    { "key": "ecology",       "name": "Экология",          "icon": "tree" },
    { "key": "transport",     "name": "Транспорт",         "icon": "car-front" },
    { "key": "announcements", "name": "Анонсы",            "icon": "megaphone" }
  ]
}

icon — имя Bootstrap Icon без префикса bi-. Для использования: <i class="bi bi-{icon}">
Всего 15 категорий, список статичный

GET /api/news/slug/{slug}

Полная информация о новости по URL-идентификатору (slug). В отличие от списка, включает полный HTML-контент (content) и галерею изображений (gallery). Возвращает 404 если новость не найдена или не опубликована.

Параметры пути

Параметр	Тип	Описание
slug *	string	URL-идентификатор новости (транслитерированный заголовок, напр. `otkrytie-novogo-parka`)

Пример запроса

curl "https://bgdportal.ru/api/news/slug/otkrytie-novogo-parka"

Пример ответа

{
  "success": true,
  "data": {
    "id": 42,
    "title": "Открытие нового парка в Богдановиче",
    "slug": "otkrytie-novogo-parka",
    "excerpt": "В центре города открылся современный парк...",
    "content": "<p>Полный HTML контент новости с <strong>форматированием</strong>...</p>",
    "category": { "key": "city", "name": "Город" },
    "image": "https://bgdportal.ru/uploads/news/park.jpg",
    "is_featured": false,
    "views": 342,
    "published_at": "2026-02-28 10:00:00",
    "url": "https://bgdportal.ru/news/otkrytie-novogo-parka",
    "author": {
      "username": "admin",
      "name": "Иван Петров"
    },
    "gallery": [
      {
        "id": 1,
        "url": "https://bgdportal.ru/uploads/news/gallery1.jpg",
        "caption": "Вид на фонтан"
      },
      {
        "id": 2,
        "url": "https://bgdportal.ru/uploads/news/gallery2.jpg",
        "caption": null
      }
    ]
  }
}

Ошибка

{
  "success": false,
  "error": { "code": 404, "message": "Новость не найдена" }
}

Неопубликованные новости (статус draft / archived) также вернут 404
Поле content содержит HTML — при рендеринге используйте санитизацию
Галерея может быть пустым массивом, если у новости нет доп. изображений

GET /api/news/{id}

Полная информация о новости по числовому ID. Ответ идентичен /api/news/slug/{slug} — включает content и gallery. Удобно когда ID уже известен из списочных API.

Параметры пути

Параметр	Тип	Описание
id *	integer	Числовой идентификатор новости

Пример запроса

curl "https://bgdportal.ru/api/news/42"

Пример ответа

{
  "success": true,
  "data": {
    "id": 42,
    "title": "Открытие нового парка в Богдановиче",
    "slug": "otkrytie-novogo-parka",
    "excerpt": "В центре города открылся современный парк...",
    "content": "<p>Полный HTML контент...</p>",
    "category": { "key": "city", "name": "Город" },
    "image": "https://bgdportal.ru/uploads/news/park.jpg",
    "is_featured": false,
    "views": 342,
    "published_at": "2026-02-28 10:00:00",
    "url": "https://bgdportal.ru/news/otkrytie-novogo-parka",
    "author": { "username": "admin", "name": "Иван Петров" },
    "gallery": []
  }
}

Ошибка

{
  "success": false,
  "error": { "code": 404, "message": "Новость не найдена" }
}

Гороскоп

1 эндпоинт

GET /api/horoscope/{sign}

Гороскоп для указанного знака зодиака. Данные получаются из внешнего источника (ignio.com) и кешируются на 3–24 часа в зависимости от периода. Если API источника недоступен — возвращается текст из кеша.

Параметры пути

Параметр	Тип	Описание
sign *	string	Знак зодиака (англ.). Допустимые значения: aries taurus gemini cancer leo virgo libra scorpio sagittarius capricorn aquarius pisces

Параметры запроса

Параметр	Тип	Описание
period	string	Период прогноза. По умолчанию: today today tomorrow week month year

Время кеширования

Период	TTL кеша	Описание
today	3 часа	Прогноз на сегодня
tomorrow	3 часа	Прогноз на завтра
week	6 часов	Прогноз на неделю
month	12 часов	Прогноз на месяц
year	24 часа	Прогноз на год

Примеры запросов

# Гороскоп для Овна на сегодня curl "https://bgdportal.ru/api/horoscope/aries" # Гороскоп для Рыб на неделю curl "https://bgdportal.ru/api/horoscope/pisces?period=week" # Годовой прогноз для Льва curl "https://bgdportal.ru/api/horoscope/leo?period=year"

Пример ответа

{
  "sign": "aries",
  "name": "Овен",
  "period": "today",
  "text": "Сегодня звёзды благоприятствуют новым начинаниям. Отличный день для важных переговоров и принятия решений. Обратите внимание на здоровье — больше отдыхайте.",
  "date": "28.02.2026"
}

Ошибка

{
  "error": "Неизвестный знак зодиака"
}

В отличие от других API, гороскоп не оборачивает данные в success/data
При невалидном period автоматически используется today (без ошибки)
Дата возвращается в формате DD.MM.YYYY (отличается от новостей)
При недоступности источника text будет: "Гороскоп временно недоступен."

Справочник знаков

Ключ	Название	Даты	Стихия
aries	Овен	21 мар — 19 апр	Огонь
taurus	Телец	20 апр — 20 мая	Земля
gemini	Близнецы	21 мая — 20 июн	Воздух
cancer	Рак	21 июн — 22 июл	Вода
leo	Лев	23 июл — 22 авг	Огонь
virgo	Дева	23 авг — 22 сен	Земля
libra	Весы	23 сен — 22 окт	Воздух
scorpio	Скорпион	23 окт — 21 ноя	Вода
sagittarius	Стрелец	22 ноя — 21 дек	Огонь
capricorn	Козерог	22 дек — 19 янв	Земля
aquarius	Водолей	20 янв — 18 фев	Воздух
pisces	Рыбы	19 фев — 20 мар	Вода

Объявления

1 эндпоинт

GET /api/subcategories/{categoryId}

Получить список подкатегорий для указанной родительской категории объявлений. Используется для динамической загрузки выпадающего списка подкатегорий при создании или фильтрации объявлений (AJAX).

Параметры пути

Параметр	Тип	Описание
categoryId *	integer	ID родительской категории объявлений

Пример запроса

# Подкатегории для категории id=1 (например, «Недвижимость») curl "https://bgdportal.ru/api/subcategories/1"

Пример ответа

{
  "success": true,
  "subcategories": [
    {
      "id": 5,
      "name": "Квартиры",
      "slug": "kvartiry"
    },
    {
      "id": 6,
      "name": "Дома",
      "slug": "doma"
    },
    {
      "id": 7,
      "name": "Земельные участки",
      "slug": "zemelnye-uchastki"
    }
  ]
}

Данные в поле subcategories (не data — отличается от новостных API)
Если категория не имеет подкатегорий — возвращается пустой массив
Возвращает только активные подкатегории
Каждая подкатегория: id, name (название), slug (URL-идентификатор)

Чаты

1 эндпоинт

GET /api/chats/unread AUTH

Получить количество непрочитанных сообщений в чатах текущего пользователя. Используется для отображения бейджа непрочитанных в шапке сайта. Аутентификация через сессионный cookie. Без активной сессии возвращает count: 0 (без ошибки).

Пример запроса

# С куками сессии (из браузера) curl -b "PHPSESSID=abc123" "https://bgdportal.ru/api/chats/unread"

Ответ (авторизован)

{
  "success": true,
  "count": 3
}

Ответ (без авторизации)

{
  "success": true,
  "count": 0
}

Данные в поле count (не data — отличается от других API)
Всегда возвращает 200 — даже без авторизации (просто count: 0)
Аутентификация через cookie PHPSESSID, API-ключи не поддерживаются
На сайте запрашивается периодически через JavaScript (polling каждые 30 сек)
Используется для бейджа 3 в шапке рядом с иконкой чатов

API Документация

Обзор API

Аутентификация

Обработка ошибок

Поиск

Новости

Гороскоп

Объявления

Чаты