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

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

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

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

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


Методы API

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

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

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

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

from - Указанные через запятую широта и долгота стартовой точки. Например "59.94173112769295, 30.33549292854919"

to - Указанные через запятую широта и долгота конечной точки.

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

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

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

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

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

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

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

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

public class PathDTO {

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

    /**
     *  Длина кратчайшего маршрута (как если бы shortest=true) в метрах, опционально, для сравнения 
     */
    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"

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

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

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

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

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

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"

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

Возвращает 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 (см. описание структуры выше)


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