API проекта Sight Safari доступно для бесплатного некоммерческого использования. Ниже приведен список условий, при которых вы можете его использовать бесплатно. Если ваш проект нарушает хоть одно из них - обратитесь к нам для получения коммерческой лицензии.
Все методы доступны только по 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" |
Некоторые методы принимают опциональный параметр 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 - Текст комментария