Назад на главную

Условия использования

API проекта Sight Safari доступно для бесплатного некоммерческого использования. Ниже приведен список условий, при которых вы можете его использовать бесплатно. Если ваш проект нарушает хоть одно из них - обратитесь к нам для получения коммерческой лицензии.

Проект Sight Safari находится в разработке, API может в любой момени измениться без предварительного уведомления.

Условия бесплатного использования:


Методы API

Все методы доступны только по https. При попытке вызова через http в ответ придет 301-перенаправление.

Ключи API

Некоторые методы принимают опциональный параметр apiKey. Это ключ апи, который можно получить по запросу. У ключа могут быть ограничения на число запросов в сутки.

Запросы без ключа попадают под правила бесплатного использования API. Мы оставляем за собой право блокировать запросы к бесплатному API от сторонних сервисов, создающие заметную нагрузку на сервер. Если вы планируете активно использовать API Sight Safari - обратитесь к нам для получения своего ключа.

Если параметр apiKey в запросе установлен, возможны три исхода:

  1. Ключ не найден: в ответ будет возвращена ошибка 403 Forbidden
  2. Ключ найден, но дневной лимит запросов к нему исчерпан: будет возвращена ошибка 429 Too many requests
  3. Ключ валиден: запрос будет обработан как обычно

Поиск маршрута

POST https://sightsafari.city/pathfindingcontroller/findpath

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

from - Адрес начала маршрута. Либо указанные через запятую широта и долгота стартовой точки ("59.94173112769295, 30.33549292854919"), либо произвольный текстовый адрес (в этом случае желательно указывать параметр desiredCoordinates как подсказку для геокодера).

to - Адрес конечной точки маршрута, в таком же формате как и from

ratio - Определяет какой маршрут хочет пользователь, более короткий или более интересный. 0 означает кратчайший (без учета достопримечательностей вообще), 1 означает оптимальное использованеи достопримечательностей, максимальное значение 1.5 заставляет искать максимально длинный путь, делающий большой крюк. Тонкая настройка довольно бессмысленна, в вебе доступны значения 0, 0.5, 1, 1.5

desiredCoordinates - Опциональная подсказка для геокодирования. Широта и долгота через запятую. Если from или to содержат строковый адрес вместо координат, его придется геокодировать и искать координаты. Для одной и той же строки геокодер может вернуть несколько результатов в разных городах (например по запросу "Витебский 21" геокодер возвращает Витебский переулок в Воронеже и Витебский проспект в Санкт-Петербурге). Если параметр desiredCoordinates задан, будет в итоге выдана точка ближайшая к ним. Если не задан - та, которую геокодер счел наиболее релевантной. Имеет смысл передавать сюда координаты города, который пользователь сейчас видит на карте.

debug - true/false, включать ли в ответ дополнительную отладочную информацию. По умолчанию false

apiKey - Опциональный ключ API (см. раздел "Ключи API" выше)

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

В ответ может прийти 404 not found если попробовать проложить маршрут за пределами поддерживаемых областей (см. ниже метод getBounds для получения списка областей).

Пустой ответ означает что маршрут не найден по какой-либо причине (внутренняя ошибка или маршрут невозможно построить).

В случае успеха ответ приходит в виде JSON и содержит в себе:

  1. Время и длину маршрута
  2. "Красоту" - некую абстрактную величину зрелищности маршрута. Алгоритм ее вычисления еще будет меняться, величина это синтетическая и не стоит к ней привязываться.
  3. Данные по кратчайшему маршруту (длину и красоту) для сранвения с построенным
  4. Список достопримечательностей для отображения на карте

Класс ответа:

public class PathDTO {

    /**
     *  Длина маршрута в метрах
     */
    public double distanceInMeters;

    /**
     *  Длина кратчайшего маршрута (как если бы ratio = 0) в метрах, опционально, для сравнения 
     */
    public Double shortestDistanceInMeters;

    /**
     * "Красота" кратчайшего маршрута
     */
    public Integer shortestScore;

    /**
     * Время на маршрут в минутах
     */    
    public long timeInMinutes;

    /**
     * Точки маршрута
     */
    public double[][] latLonPoints;

    /**
     * "Красота" маршрута, абстрактное число, чем оно больше тем больше достопримечательностей на маршруте
     */
    public double score;

    /**
     * Достопримечательности видимые с маршрута
     */
    public List<SightAreaDTO> sightAreas;
}

Класс SightAreaDTO описывает достопримечательность, влияющую на построенный маршрут (приведена только часть полей):

public class SightAreaDTO {

    /**
     * ID объекта во внешней системе (например в OSM)
     */
    private String originId;

    /**
     * Опциональное имя объекта
     */
    private String name;

    /**
     * Опциональное текстовое описание объекта
     */
    private String description;
    
    /**
     * Тип объекта 
     */
    private SightAreaType type;

    /**
     * Массив координат объекта
     */
    private double[][] coordinates;

    /**
     * Центроид геометрии объекта, широта и долгота
     */
    private double[] centroid;
    
    /**
     * Опциональная ссылка на страницу объекта. На Wikipedia или на собственный веб-сайт.
     */
    private String link;

    /**
     * Тип геометрии объекта
     */
    private GeometryType geometryType;
}

Типы объектов:

Типы геометрии

Дырки и множественные контуры в полигонах не поддерживаются. Если у объекта несколько контуров, то он придет в виде нескольких отдельных SightAreaDTO. Так что при отображении например списка имен нужно их фильтровать и проверять на дубликаты.

Поиск кругового маршрута

Ищет маршут, начинающийся и заканчивающиеся в той же точке и занимающий примерно указанное время

POST https://sightsafari.city/pathfindingcontroller/findcircularpath

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

from - Указанные через запятую широта и долгота стартовой точки (например "59.94173112769295, 30.33549292854919"), либо строковый адрес (в этом случае желательно указывать параметр desiredCoordinates для более точного определения адреса)

minutes - Желаемая продолжительность маршрута в минутах, от 30 до 180 включительно

desiredCoordinates - Опциональная подсказка для геокодера. См. значение этого параметра выше в описании запроса findPath

debug - Если true то выдаст дополнительную отладочную информацию

apiKey - Опциональный ключ API (см. раздел "Ключи API" выше)

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

Такая же как и в обычном поиске пути, см. выше.

Информация о точке

GET https://sightsafari.city/pathfindingcontroller/whatishere

Возвращает список объектов, влияющих на маршруты в заданной точке

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

lat - Широта точки

lon - Долгота точки

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

class WhatIsHereDTO {
    /**
     * Широта точки
     */
    public double lat;
    
    /**
     *  Долгота точки
     */
    public double lon;

    /**
     * Список объектов, положительно влияющих на привлекательность точки для пешеходов 
     */
    public List<SightAreaDTO> positiveAreas;

    /**
     * Список негативно (типа NEGATIVE) влияющих объектов
     */
    public List<SightAreaDTO> negativeAreas;

    /**
     * Итоговый вес точки, от 1 до 0.05, чем меньше тем лучше. 
     */
    double coeff;
}

Геокодирование

Метод для поиска координат по названию. Использует OSM-ный геокодер который работает довольно плохо и не умеет нормально обрабатывать произвольные запросы.

GET https://sightsafari.city/pathfindingcontroller/findlocation

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

query - Строка с запросом, например "Ленинский пр. 42"

desiredCoordinates - Опциональные координаты, lat-lon через запятую. Если указаны и если геокодер по запросу вернул несколько координат - будут выданы ближайшие к desiredCoordinates. В вебе, например, имеет смысл передавать сюда координаты центра карты, на которую смотрит сейчас пользователь.

apiKey - Опциональный ключ API (см. раздел "Ключи API" выше)

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

Возвращает 404 not found если по данному запросу ничего не найдено. Иначе возвращает JSON с координатами точки.

{
    "x":54.7629999,
    "y":32.0459914,
    "z":0.0
}

Границы участков

Поиск путей работает не по всей карте, а лишь там где загружены OSM данные, в заданном наборе прямоугольных областей. На веб-фронтенде sightsafari.city эти области отмечены красным пунктиром. Этот метод позволяет получить границы областей, которые затем можно использовать для проверки пользовательского ввода.

GET https://sightsafari.city/pathfindingcontroller/showBounds

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

Список координат левых нижних и правых верхних углов прямоугольников, ограничивающих области доступные для поиска

[
    {
        /**
         * Название области
         */
        "name":"Санкт-Петербург",

        /**
         * Координаты левой нижней и правой верхней точки
         */
        "coordinates": [
            [59.8082,29.6452],
            [60.1073,30.5612]
        ],
        
        /**
         * Приоритет сортировки. По умолчанию 0. Используется для отображения важных городов (столиц) вверху списка, области с более
         * высоким приоритетом должны показываться пользователю раньше в списках выбора области.
         */
        "sortPriority":5
    },
    {
        "name":"Вологда",
        "coordinates": [
            [59.1714,39.7272],
            [59.2792,40.0225]
        ],
        "sortPriority":0
    }
]

Отображение достопримечательностей

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

GET https://sightsafari.city/pathfindingcontroller/showSightAreas

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

lat - широта точки

lon - долгота точки

Точка не обязательно должна принадлежать поддерживаемой зоне, будет выбрана ближайшая доступная зона.

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

Список SightAreaDTO (см. описание структуры выше)


Остались вопросы? Задайте их в нашей группе Вконтакте!