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

Справка по API

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

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

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

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


Методы API

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

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

При нормальной работе сервера в ответ всегда приходит 200 код вместе с JSON. Возможные ошибки на сервере классифицированы и приходят внутри ответа с кодом и описанием.

{
  "code": 0,
  "description": "description",
  "body": {}
}

Коды ошибок

Код Описание
0 "Completed successfully"
1 "Not a valid request"
2 "No area found for these points"
3 "Daily quota for API key exceeded"
4 "API Key does not exist"
5 "{} is neither valid coordinates nor address string"
6 "Coordinates not found"
7 "Coordinate found but is not inside our area"
8 "Address not found"
9 "Internal error"
10 "Failed to build path"
11 "There are not enough POIs nearby to build interesting route"
12 "Route Entry not found"
13 "Impossible to reach given POI search area from starting point within time limit"

Ключи API

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

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

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

GET https://sightsafari.city/api/v1/routes/direct POST https://sightsafari.city/api/v2/routes/direct

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

В GET запрос параметры передаются как http параметры запроса.

В POST запрос параметры передаются в виде JSON объекта в теле запроса, содержащего указанные ниже поля.

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

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

to - Используется только в GET запросе. Адрес конечной точки маршрута, в таком же формате как и from

intermediatePoints - Используется только в GET запросе. Опциональный список адресов промежуточных точек, куда нужно зайти по пути. Формат такой же, как и у from

points - Применяется только для POST запросов. Содержит все точки, включая начальную и конечную, между которыми должен быть построен маршрут.

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

locale - Локаль пользователя. По дефолту "en". На данный момент поддерживаются русский и английский языки.

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

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

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

filter - Опциональный фильтр для типов достопримечательностей (см. список типов ниже). Если он задан - при построении маршрута будут учитываться только достопримечательности заданных типов. Может указываться несколько раз: filter=PARK&filter=WATER. По умолчанию (если фильтр явно не задан) используются все типы достопримечательностей.

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

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;
    
    /**
    * Уникальный короткий URL для открытия этого маршрута, его можно использовать чтобы делиться маршрутом 
    */
    public String shareURL;
    
    /**
    * Параметр с которым был построен маршрут, для прямых маршрутов - значение интересности, для круговых - количество минут 
    */
    public Double pathParam;
}

Класс 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 List<String> links;
    
    /** 
    * Опциональное текстовое описание из википедии
    * */
    
    private String wikiDescription;

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

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

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

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

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

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

GET https://sightsafari.city/api/v1/routes/circle POST https://sightsafari.city/api/v2/routes/circle

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

В GET запрос параметры передаются как http параметры запроса. На сервере есть ограничение размера строки запроса в 8192 байт. Этот предел может быть легко превышен при задании сложного полигона в poiSearchArea. Поэтому для таких запросов лучше использовать POST.

В POST запрос параметры передаются в виде JSON объекта в теле запроса, содержащего указанные ниже поля.

Обязательными являются параметры from и minutes

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

locale - Локаль пользователя. По дефолту "en". На данный момент поддерживаются русский и английский языки

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

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

poiSearchArea - Опциональная GeoJSON строка с областью поиска достопримечательностей. Используется для ограничения поиска и выбора желаемого направления пути. Если она не задана, достопримечательноти будут искаться во всех направлениях вокруг стартовой точки.

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

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

filter - Фильтр по типам достопримечательностей. См. описание к запросу findPath

Класс ответа

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

Загрузка ранее сохраненного маршрута

Загружает ранее созданный маршрут по его ID. ID маршрута это последняя часть, приходящая в поле shareURL маршрута

GET https://sightsafari.city/api/v1/routes/load

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

routeId - ID маршрута

locale - локаль в которой будут указаны названия

Класс ответа

Тот же что и у других методов прокладки путей.

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

GET https://sightsafari.city/api/v1/geography/environment

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

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

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

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

locale - Локаль пользователя. По дефолту "en". На данный момент поддерживаются русский и английский языки

Класс ответа

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/api/v1/location

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

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

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

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

Класс ответа

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

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

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

GET https://sightsafari.city/api/v1/geography/bounds

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

locale - Локаль пользователя. По дефолту "en". На данный момент поддерживаются русский и английский языки

Класс ответа

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

[
    {
        /**
        * ID страны, -1 для отдельного списка городов без стран
        */
        "id": 1,
        
        /**
        * Название страны
        */
        "name": "Россия",

        /**
        * Приоритет страны
        */
        "sortPriority": 5,

        /**
        * Города в стране, для которых поддерживается навигация
        */

        "cities": [
            {
                /**
                * ID города
                */
                "id": 2,
                
                /**
                 * Название области
                 */
                "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/api/v1/geography/sights

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

minLat, minLon, maxLat, maxLon - границы прямоугольника

locale - Локаль пользователя. По дефолту "en". На данный момент поддерживаются русский и английский языки

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

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

Оценить маршрут

Сохраняет на сервере оценку данного маршрута по мнению пользователя. Оценки могут использоваться в улучшении и отладке алгоритмов.

POST /api/v1/routes/rateroute/

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

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

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

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

pathJson - JSON объект маршрута, полученный из метода getPath.

rating - Целочисленное значение от 1 до 5

comment - Текст комментария


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