Введение

API Яндекс Карты — это набор картографических, геолокационных и навигационных решений, которые позволяют бизнесу использовать актуальные геоданные, встраивать карты на сайты и в приложения, а также решать задачи, связанные с маршрутизацией и навигацией.

С помощью продуктов API Яндекс Карт можно создавать и настраивать под себя интерактивные и статические карты, получать данные о пробках в реальном времени, искать адреса и объекты, строить маршруты, определять местоположение и многое другое.

Данная документация помогает разобраться в принципах работы геопродуктов, их технологических основах и том, как использовать инструменты API Яндекс Карт для развития бизнеса и оптимизации процессов компании.

Клиент-серверное взаимодействиеКлиент-серверное взаимодействие

Для начала стоит понять, что такое клиент-серверное взаимодействие.
Все умеют пользоваться браузером и искать информацию в интернете. Но что происходит после ввода адреса, например https://yandex.ru/maps, в адресной строке?

Сначала браузер отправляет запрос на получение данных через интернет, а сервер Яндекса предоставляет эти данные.

В данной схеме браузер — это клиент, или заказчик данных, а Яндекс — сервер, то есть поставщик данных. Схема называется клиент-серверной архитектурой, а процесс обмена данными — клиент-серверным взаимодействием.

Сервер — это компьютер, который обрабатывает запросы клиентов и отдает разные виды контента: текст, изображения, видеоролики и веб-страницы.

Клиентов может быть много. Например, один и тот же пользователь может одновременно открыть Яндекс Карты на компьютере, планшете и мобильном телефоне. Количество клиентов может легко достигать миллионов. Все клиенты взаимодействуют с серверами с помощью HTTP-запросов.

HTTP и HTTPSHTTP и HTTPS

Язык — это система знаков и правил, созданная для того, чтобы люди могли формулировать мысли и передавать информацию. Язык используют все участники коммуникации, и это позволяет им понимать друг друга.

Для общения между клиентом и сервером тоже есть специальные языки. Самые популярные среди них — это HTTP и HTTPS.

HTTP (HyperText Transfer Protocol) — язык общения, или протокол для обмена информацией между компьютерами. С помощью HTTP можно передавать текст, фото, видео и другие файлы.

Клиент и сервер знают язык HTTP и обмениваются данными с помощью HTTP-запросов и HTTP-ответов.

С помощью HTTP-запросов можно получать, изменять или удалять нужные данные.

HTTP-запрос и HTTP-ответ состоят из двух частей: заголовка и тела запроса. Тело запроса содержит данные — текст, изображения или видео — и инструменты для их отображения — HTML- и CSS-код, а также JS-скрипты. Всё это показывает браузер.

Здесь можно провести аналогию с бумажными письмами: подпись и адрес на конверте — заголовок запроса, а текст письма — тело запроса.

Протокол HTTP не защищает передаваемые данные, и злоумышленники могут их перехватить.

В чем разница между HTTP и HTTPSВ чем разница между HTTP и HTTPS

Чтобы решить проблему безопасности передаваемых данных, придумали протокол HTTPS (Hypertext Transfer Protocol SECURE) — расширенную версию протокола HTTP с поддержкой шифрования.

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

APIAPI

API (Application Programming Interface) — это инструмент, который помогает разным приложениям и сервисам «общаться» друг с другом. По сути, это набор инструкций и правил, который позволяет передавать данные из одного приложения в другое через HTTP-запросы и HTTP-ответы.

Проще говоря, API — это как приложение для вызова такси. Вы не звоните всем водителям подряд, чтобы узнать, кто свободен. А просто открываете приложение (клиент), указываете маршрут и класс автомобиля (HTTP-запрос). Приложение отправляет запрос на сервер, получает ответ водителя (HTTP-ответ) и отправляет вам уведомление: машина прибудет через 5 минут.

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

Запрос к API можно уточнить с помощью параметров — конкретной информации, которая помогает серверу понять, что именно нужно. Например, это может быть команда на поиск объекта по определенному адресу или формату данных. Это похоже на то, как при поиске маршрута в навигаторе вы уточняете условия: вместо «проложить маршрут» вы добавляете параметры — «избегать пробок» или «не использовать платные дороги». Чем точнее параметры, тем более подходящий результат вернет API.

Пример запроса к API Геокодера:

https://geocode-maps.yandex.ru/1.x/?apikey=YOUR_API_KEY&geocode=25.197300,55.274243&format=json, 

где:

• apikey — персональный ключ, который идентифицирует пользователя API;
• geocode — координаты для поиска адреса;
• format — желаемый формат ответа.

Некоторые параметры обязательны, другие можно не указывать. Все возможные параметры подробно описаны в документаци и к продуктам.

Примеры параметров:

Для работы с продуктами API Яндекс Карт нужно получить уникальный API-ключ — буквенно-числовой идентификатор, который указывает серверу Яндекса, что запрос отправлен конкретным пользователем. Ключи помогают учитывать статистику запросов для аналитики и расчетов по тарифам, а также ограничивать использование продуктов, например, при превышении лимита или несвоевременной оплате.

Ключ уникален для каждого продукта и пользователя. Его надо передавать в HTTP-запросе каждый раз при обращении к сервисам Яндекса.

Пример запроса:

https://tiles.api-maps.yandex.ru/v1/tiles/?x=9902&y=5137&z=14&lang=ru_RU&l=map&apikey=YOUR_API_KEY, 

где YOUR_API_KEY — ваш персональный API-ключ. Получить ключ и настроить его можно в кабинете разработчика.

Ограничения запросовОграничения запросов

Если приложение делает слишком много запросов к API, сервер может замедлиться или отказать в обслуживании. Чтобы этого избежать, устанавливают ограничение RPS (requests per second), которое регулирует число запросов, обрабатываемых за секунду. Это помогает поддерживать стабильную работу и своевременно обрабатывать запросы.

Ограничение RPS также предотвращает перегрузку во время DDoS-атак — когда злоумышленники отправляют миллионы запросов к серверу за секунду, чтобы парализовать его работу и заблокировать всю инфраструктуру. RPS позволяет отсечь лишние запросы, защищая сервер и обеспечивая корректную обработку запросов реальных пользователей.

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

Для каждого ключа доступна индивидуальная настройка RPS. Конкретные значения для различных продуктов можно найти в документации, например RPS для Получения деталей маршрута.

Ограничения по RPS помогают управлять размерами инфраструктуры: они позволяют точно рассчитать, что при Х клиентах и не более Y запросов в секунду имеющихся Z серверов будет достаточно для стабильной работы без перегрузок.

SDKSDK

SDK (Software Development Kit) — это набор средств и инструментов для разработки, который помогает создавать приложения. В него входят готовые библиотеки, документация, примеры кода и иногда API, что облегчает разработчику создание нужного функционала. SDK предоставляет всё необходимое для работы на конкретной платформе, например Android или iOS.

Другими словами, SDK — это как блочный конструктор с готовыми деталями и пошаговой инструкцией. Вместо того чтобы искать или подбирать подходящие элементы и продумывать, как их соединить, вы используете готовые — и быстро собираете нужный объект.
Без SDK вам пришлось бы создавать и продумывать всё с нуля, а с ним вы получаете готовое решение.

Разница между SDK и APIРазница между SDK и API

API объясняет, как приложения могут взаимодействовать и обмениваться данными. Он описывает набор правил и методов, с помощью которых одно приложение может запросить информацию или выполнять действия с данными на сервере.

SDK включает в себя API, а также целый набор инструментов, библиотек, примеров кода и документации. Он упрощает разработку и позволяет быстро создавать функционал.

Все продукты API Яндекс Карт делятся на API и SDK.

JavaScript API относится к SDK, потому что содержит в себе встроенные API, которые позволяют легко и быстро интегрировать карту на сайт. Название, которое содержит API, сложилось исторически из-за того, что в JS API интегрированы многие функции, которые обычно предоставляются отдельными API.

Многие API Яндекс Карт уже встроены в SDK, например Tiles API или API Геокодера. Их не нужно оплачивать отдельно — они включены в цену SDK. Если нужно использовать API, которые не интегрированы в другие продукты, например API Матрицы расстояний или Локатор API, то их нужно купить отдельно, а затем использовать в SDK. Они тарифицируются независимо от самого SDK.

API Яндекс Карт поддерживает интеграцию с собственными разработками и сторонними SDK.

С подробной информацией о всех доступных продуктах и их стоимости вы можете ознакомиться на официальном сайте.

SaaSSaaS

SaaS (Software as a Service) — это модель, при которой программное обеспечение и серверы находятся на стороне поставщика, а клиент получает доступ к сервисам через интернет.

Плюсы:

Минусы:

Продукты API Яндекс Карт в основном предоставляются по модели SaaS. Но постепенно происходит процесс внедрения модели On-premise, напимер JavaScript API и Геокодер.

On-premiseOn-premise

On-premise — это модель, при которой программное обеспечение и серверы устанавливаются прямо у клиента, внутри его инфраструктуры.

On-Premise Maps — это набор сервисов, которые устанавливаются в инфраструктуре заказчика. Он позволяет использовать геосервисы Яндекса без доступа к интернету. Сервисы, развернутые в инфраструктуре компании, предоставляют функции, аналогичные тем, которые мы предоставляем через API в SaaS-модели. В этом случае API-запросы направляются не на серверы Яндекса через интернет, а на локальный сервер клиента.

Плюсы:

Минусы:

ВерсионностьВерсионность

Продукты API Яндекс Карт находятся в постоянном развитии: регулярно устраняются ошибки, расширяется функционал и совершенствуются имеющиеся возможности.

Это видно на примере различных версий MapKit Mobile SDK.

Клиентам и партнерам важно следить за актуальными версиями API и SDK и переходить на новые стабильные версии. Это нужно по нескольким причинам:

• Оптимизация и улучшение производительности. Новые версии содержат улучшенные алгоритмы, которые делают работу с геосервисами быстрее, стабильнее и не содержат ошибок предыдущих версий.
• Использование новых функций. В новых версиях появляются дополнительные возможности, которых нет в прежних.
• Сохранение поддержки. Со временем мы прекращаем поддерживать старые версии API. Поэтому важно вовремя планировать переход на новые, чтобы не перегружать команду разработки срочными задачами миграции.