Формат запросов

Для отправки API-запросов используется HTTP-метод POST или GET. В VK API эти методы равнозначны.

Важно! Для работы с API используйте протокол HTTPS.

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

Синтаксис запросов

Структура HTTP-запроса:

http

GET /method/<имя-API-метода>?<параметр1=значение1>&<параметр2=значение2> HTTP/1.1
Host: <адрес-сервера>
Authorization: Bearer <КЛЮЧ_ДОСТУПА>

Заголовки

При обращении к VK API используйте следующие HTTP-заголовки:

Authorization

Передавайте ключ доступа в каждом запросе в заголовке Authorization. В описании метода указан тип ключа, который нужен для выполнения запроса: ключ доступа пользователя, сообщества или сервисный. Ключ доступа передаётся в формате:

Authorization: Bearer <КЛЮЧ_ДОСТУПА>

Content-Type

Заголовок Content-Type определяет формат данных, которые вы отправляете в теле POST-запроса.

Поддерживаемые значения:

•
application/x-www-form-urlencoded — параметры передаются в формате key=value&key2=value2 в теле запроса. Подходит для большинства запросов с небольшим объёмом данных.
•
multipart/form-data — параметры передаются частями (form-data). Используйте это значение, если вы отправляете файлы или бинарные данные, а также если суммарный размер передаваемых данных больше 2 Кбайт.
•
Значение application/json в настоящее время не поддерживается.

В curl формат данных можно определить при помощи флагов:

•
Флаг -F формирует multipart/form-data.

•
Флаг -d формирует application/x-www-form-urlencoded.

Адрес сервера

В каждом запросе необходимо указать доменное имя сервера VK API: api.vk.ru.

При создании мини-приложений или игр мы рекомендуем определять адрес сервера динамически, а не фиксировать его в коде. Подробнее:

Имя API-метода

В каждом запросе необходимо указывать <имя-API-метода> — раздел и операцию для вызова, например users.get. Имя метода чувствительно к регистру.

Полный список методов, доступных в VK API — в разделе Методы API.

Параметры

Большинство методов поддерживают входные параметры, передаваемые в URL после символа ? или в теле POST-запроса.

В URL параметры задаются как последовательность пар имя=значение, разделённых символом &.

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

Обязательные параметры

Для каждого запроса необходимо указать параметр v — используемая версия API. Параметр влияет на формат ответов различных методов. Актуальная версия API — 5.131.

Общие параметры

Помимо входных параметров существуют общие параметры, которые могут быть использованы во всех методах:

•
lang — определяет язык, на котором будут возвращаться различные данные, например названия стран и городов. Может содержать строковое обозначение языка или его идентификатор. Кириллические имена будут автоматически транслитерированы в латиницу для всех языков, кроме русского, украинского и белорусского. Возможные значения:
- •
  ru (0) — русский.
- •
  uk (1) — украинский.
- •
  be (2) — белорусский.
- •
  en (3) — английский.
- •
  es (4) — испанский.
- •
  fi (5) — финский.
- •
  de (6) — немецкий.
- •
  it (7) — итальянский.
•
test_mode=1 — тестовый режим, позволяет выполнять запросы из нативного приложения без его включения на всех пользователей.

Ограничения

В VK API существуют ограничения на количество запросов в секунду. Они зависят от типа ключа доступа и секции методов. Если превысить такое ограничение, сервер вернёт ошибку: 6 "Too many requests per second."

Помимо ограничений на частоту обращений, существуют и количественные ограничения на вызов однотипных методов. Мы не предоставляем информацию о точных лимитах.

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

Ключ	Ограничения
Ключ доступа пользователя	3 запроса в секунду.
Ключ доступа сообщества	20 запросов в секунду.
Сервисный ключ доступа	Ограничения зависят от количества пользователей приложения: • До 10 000 — 5 запросов в секунду. • До 100 000 — 20 запросов в секунду. • До 500 000 — 40 запросов в секунду. • До 1 000 000 — 50 запросов в секунду. • Более 1 000 000 — 60 запросов в секунду. Методы секции `secure` имеют дополнительные ограничения по количеству пользователей: • До 100 000 — 8 запросов в секунду. • До 1 000 000 — 20 запросов в секунду. • Более 1 000 000 — 35 запросов в секунду.

Примеры

Ниже представлены примеры вызова метода users.get разными способами.

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

•
Идентификатор пользователя: user_ids=743784474.
•
Дата рождения: fields=bdate.
•
Версия API (обязательный параметр): v=5.131.

Заголовки:

•
Authorization: Bearer <КЛЮЧ_ДОСТУПА>

Ожидаемый результат во всех примерах одинаковый: в response вернётся json с датой рождения пользователя. Пример ответа:

JSON

{
  "response": [
    {
      "id": 743784474,
      "first_name": "Персик",
      "last_name": "Рыжий",
      "bdate": "21.12.2000"
    }
  ]
}

Запрос через cURL

cURL-запрос для вызова метода VK API:

Bash

curl 'https://api.vk.ru/method/users.get' \
  -H 'Authorization: Bearer <КЛЮЧ_ДОСТУПА>' \
  -F 'user_ids=743784474' \
  -F 'fields=bdate' \
  -F 'v=5.131'

Запрос из PHP

PHP-скрипт для вызова метода VK API:

PHP

<?php
$user_id = 210700286;
$request_params = array(
    'user_id' => $user_id,
    'fields' => 'bdate',
    'v' => '5.52',
);

$get_params = http_build_query($request_params);

$context = stream_context_create([
    'http' => [
        'header' => "Authorization: Bearer <КЛЮЧ_ДОСТУПА>\r\n",
    ],
]);

$result = json_decode(file_get_contents('https://api.vk.ru/method/users.get?' . $get_params, false, $context));
echo ($result->response[0]
    ->bdate);
?>

Запрос с использованием Open API

Open API — JS-библиотека для упрощения работы с VK API на внешних сайтах. Open API берёт на себя отправку запроса и обработку ответа, а также процедуру авторизации.

Фрагмент HTML со скриптом на JavaScript для вызова метода VK API:

HTML

<script type="text/javascript">
   VK.Api.call('users.get', { user_ids: 210700286, fields: 'bdate' }, function(r) {
   if(r.response) {
   alert(r.response[0].bdate);
   }
   });
</script>