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

Terms of Use

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"

Ключи API

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

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

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

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

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

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

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

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;
}

Класс 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/circular

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

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

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

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

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

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

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

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

Класс ответа

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

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

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

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

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

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

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 - Текст комментария


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