Введение

Данный API предназначен для быстрого получения информации о ближайших бомбоубежищах на основе географических координат пользователя. Он позволяет легко интегрировать поиск убежищ в сторонние приложения или сайты.

Назначение API

API предоставляет данные о местах убежищ, расположенных в заданном прямоугольнике с центром в указанной точке. Это помогает пользователям быстро находить ближайшие объекты и планировать маршрут до них.

Формат ответа (JSON)

Все данные возвращаются в формате JSON — удобном для обработки на клиенте.

Публичный доступ, не требует авторизации

API открыт для публичного использования и не требует ключей или других методов аутентификации.

Базовый URL и метод запроса

• Метод: GET
• URL: /api/load-all-places.php

Обязательные параметры запроса

• lat — широта в градусах (например, 32.09025)
• lng — долгота в градусах (например, 34.77698)
• distance — дистанция поиска в километрах (например, 0.125)

Принцип работы

Поиск ведётся по прямоугольнику с центром в координатах lat, lng. Ширина и высота прямоугольника равны 2 × distance. Это значит, что возвращаются все объекты в квадрате со стороной в 2 раза больше заданной дистанции.

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

https://bombshelternearby.info/api/load-all-places.php?lat=32.0902518021144&lng=34.77698936985843&distance=0.125

Этот запрос вернёт бомбоубежища на расстоянии до 125 метров от центра Тель-Авива.

Структура ответа

API возвращает JSON-объект следующей структуры:

{
  "success": true,
  "data": [
    {
      "location": {
        "lat": 32.090674,
        "lng": 34.776631
      },
      "source": "<a href=\"https://safewayil.ovh/\" target=\"_blank\">SafeWay</a>",
      "photos": [],
      "description": "Описание объекта с возможным HTML-контентом.",
      "iconOptions": {
        "background": "#FF000050",
        "borderColor": "white",
        "scale": 1.5
      }
    },
    ...
  ],
  "timing": {
    "safeway": 0.0586,
    "rileri": 0.0007,
    "amechad": 0.0002,
    "tlv": 0.0006,
    "posted": 0.0017,
    "filtering": 0.0023,
    "total": 0.0642
  }
}

Пояснение по полям:

• success (boolean) — статус выполнения запроса. true — запрос выполнен успешно, false — ошибка.
• data (массив объектов) — список найденных бомбоубежищ, каждое описано следующим образом:
  • location (объект) — географические координаты:
    • lat (float) — широта в градусах.
    • lng (float) — долгота в градусах.
  • source (string) — HTML-ссылка на источник данных об объекте, может использоваться для отображения ссылки в интерфейсе.
  • photos (массив строк) — список URL-адресов фотографий объекта. Может быть пустым.
  • description (string) — текстовое описание объекта (на языке источника данных!), допускается использование HTML-тегов для форматирования.
  • iconOptions (объект) — параметры отображения маркера на карте:
    • background (string) — цвет фона маркера в формате HEX с прозрачностью (например, #FF000050).
    • borderColor (string) — цвет рамки маркера.
    • scale (float) — масштаб маркера.
• timing (объект) — статистика времени обработки данных, полезна для мониторинга производительности:
  • Поля с именами источников (safeway, rileri и др.) — время обработки соответствующих наборов данных (в секундах). Позволяют также определить количество источников данных.
  • filtering — время, затраченное на фильтрацию данных по расстоянию от заданной точки.
  • total — общее время обработки запроса.

---

Рекомендации по использованию:

• Поле data содержит все объекты, попадающие в указанный в запросе периметр поиска.
• Для отображения маркеров на карте рекомендуется использовать координаты из location и стилизовать маркеры с помощью параметров из iconOptions.
• Поле source можно использовать для ссылки на оригинальный источник данных.
• Описание description может содержать HTML, поэтому при отображении учитывайте безопасность и корректность рендеринга.
• Время обработки из timing не обязательно для отображения, но может быть использовано для логирования и оптимизации.

Ограничения и рекомендации

• Максимальная разумная дистанция поиска — около 5 км, чтобы не перегружать сервер и клиент
• Числовые значения должны использовать точку . как десятичный разделитель
• Для снижения нагрузки данные кешируются. Рекомендуется не делать запросы чаще, чем раз в несколько секунд

Контакты

Если у вас возникли вопросы по API, вы можете связаться с нами по электронной почте, указанной в разделе Политика конфиденциальности.