Как отправлять GET-запросы в Python с библиотекой Requests

Библиотека Requests отправляет GET-запросы из Python несколькими строками кода. Вы создадите виртуальное окружение, установите пакет, передадите параметры и заголовки, проверите статус и достанете поле из JSON. Такой python get запрос подойдет для первого знакомства с API.

В конце у вас останется функция с таймаутом и обработкой сетевых ошибок.

Как работают HTTP-запросы в Python

Клиент отправляет запрос на URL, а сервер возвращает ответ. Браузер показывает полученный HTML, а Python-скрипт получает тело ответа в объекте Response.

Метод GET обычно запрашивает данные. Метод POST передает данные в теле запроса, а PUT изменяет ресурс. Конкретное поведение задает сервер API.

Параметры URL передавайте через params. Символы ?, & и = разделяют части адреса, но сами по себе не определяют HTTP-метод.

Requests Python 3 – установка через pip install requests в виртуальное окружение

Пакет Requests устанавливает менеджер pip. Виртуальная среда хранит зависимости проекта отдельно от системного Python.

1. Откройте терминал в папке проекта и создайте среду командой python -m venv .venv. Модуль venv создаст каталог .venv.
2. Активируйте среду командой для своей оболочки: в Windows cmd выполните .venv\Scripts\activate.bat, в PowerShell – .\.venv\Scripts\Activate.ps1, в bash на Linux или macOS – source .venv/bin/activate.
3. Установите пакет командой pip install requests.

После активации приглашение терминала обычно получает префикс (.venv). Теперь команда pip install requests устанавливает библиотеку в эту среду.

Если оболочка блокирует активацию, установите пакет через Python самого окружения.

# Windows: установка без активации
.venv\Scripts\python.exe -m pip install requests

# Linux или macOS: установка без активации
.venv/bin/python -m pip install requests

Создайте файл check_requests.py и добавьте проверку импорта.

import requests

print(requests.__version__)

Запустите файл командой python check_requests.py. Консоль напечатает версию установленного пакета. Без активации используйте .venv\Scripts\python.exe check_requests.py в Windows или .venv/bin/python check_requests.py в Linux и macOS.

Первый python requests get запрос

Для первого примера обратитесь к корневой точке GitHub REST API. Скрипт получит ответ сервера, но не отрисует HTML, как браузер.

Сохраните код в файл script.py в папке проекта.

import requests

res = requests.get('https://api.github.com', timeout=10)
print(res)
print(res.status_code)

В активированном окружении запустите файл командой python script.py.

При успешном ответе консоль покажет две строки.

<Response [200]>
200

Число 200 означает успешный ответ сервера.

Скрипт получает тело ответа как текст, байты или разобранные данные JSON. Браузер превращает HTML в страницу, а Requests возвращает его программе.

Объект Response хранит статус, заголовки, URL и тело ответа. Методы requests.post() и requests.put() решают другие задачи.

Параметры GET-запроса через params

Передайте параметры словарем в аргументе params. Requests добавит их к URL и закодирует специальные символы.

import requests

url = 'https://api.github.com/search/repositories'
params = {'q': 'python requests', 'per_page': 1}

res = requests.get(url, params=params, timeout=10)
print(res.url)
print(res.status_code)

Параметр q задает поисковую фразу. Параметр per_page задает размер страницы ответа.

Итоговый адрес находится в res.url.

Requests сам добавляет к нему закодированные значения словаря. В напечатанном адресе вы увидите q=python+requests и per_page=1.

Не собирайте строку запроса вручную. Словарь params снижает риск ошибок с пробелами и специальными символами.

Коды состояния и проверка ответа

Поле res.status_code содержит числовой код ответа. Свойство res.ok возвращает True для ответа с кодом меньше 400.

if res.ok:
    print('Response OK')
else:
    print('Response Failed', res.status_code)

print(res.status_code == requests.codes.ok)

Условие if res опирается на то же поведение, что и res.ok. Сравнение с requests.codes.ok проверяет конкретно код 200.

Для ответа 404 свойство res.ok даст False.

Само это свойство не создает исключение.

Как передать заголовки в Requests через headers

Заголовки описывают запрос и формат данных. Передайте словарь headers в вызов requests.get().

import requests

url = 'https://api.github.com'
headers = {
    'User-Agent': 'python-requests-example',
    'Accept': 'application/json',
}

res = requests.get(url, headers=headers, timeout=10)
print(res.status_code)
print(res.headers.get('content-type'))

Заголовок User-Agent описывает клиент. Заголовок Accept сообщает серверу предпочитаемый формат ответа.

Если API поддерживает токены, передавайте их в заголовке Authorization. Секрет не храните в исходном коде и не добавляйте в URL.

Этот словарь показывает формат авторизации; учебным запросам к корню токен не нужен.

headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN',
}

В запросе с авторизацией замените YOUR_TOKEN настоящим токеном. Не отправляйте эту строку-заглушку вместе с учебными запросами.

Заголовки ответа доступны через res.headers. Поле content-type подсказывает, получил ли скрипт JSON, HTML или другой формат.

Текстовый ответ и JSON-поля

Свойство res.text возвращает тело как строку. Свойство res.content возвращает исходные байты.

Запустите этот пример отдельно: замените им содержимое script.py и выполните python script.py. Код заново получает корневой ответ без авторизации и проверяет статус. Настоящий токен для примера не нужен.

import requests

res = requests.get(
    'https://api.github.com',
    headers={
        'User-Agent': 'python-requests-example',
        'Accept': 'application/json',
    },
    timeout=10,
)
res.raise_for_status()

print(res.text)
print(res.content[:20])
print(res.encoding)
print(res.url)

data = res.json()
print(data['current_user_url'])

Последняя строка успешного примера напечатает https://api.github.com/user.

Свойство res.encoding показывает выбранную кодировку. Свойство res.url содержит итоговый URL с параметрами.

JSON-ответ разбирайте методом res.json(). Сохраните результат в переменную data, чтобы не затенять стандартный модуль json.

Корневой ответ GitHub API содержит поле current_user_url. Для другого API сначала посмотрите структуру словаря, затем обратитесь к нужному ключу.

Обработка ошибок GET-запроса

Проверка status_code сообщает о проблеме, но сама не прерывает программу. Метод res.raise_for_status() создает HTTPError для ответа с ошибкой 4XX или 5XX.

import requests

try:
    res = requests.get(
        'https://api.github.com/does-not-exist',
        timeout=10,
    )
    res.raise_for_status()
except requests.exceptions.HTTPError as error:
    print('HTTP error:', error)
except requests.exceptions.Timeout:
    print('Request timed out')
except requests.exceptions.ConnectionError:
    print('Connection error')
else:
    data = res.json()
    print(data)

При ответе 404 обработчик напечатает начало строки HTTP error: 404 Client Error. Полное сообщение содержит описание ошибки и URL.

Параметр timeout=10 задает таймаут подключения и ожидания данных в секундах.

Этот параметр не ограничивает общее время скачивания десятью секундами. При чтении ответа таймаут срабатывает, если сервер слишком долго не передает данные. Без timeout Requests может ждать бесконечно.

Проверьте ошибку авторизации отдельным запросом к endpoint /user.

import requests

try:
    res = requests.get(
        'https://api.github.com/user',
        headers={'Authorization': 'Bearer invalid-token'},
        timeout=10,
    )
    print(res.status_code)
    res.raise_for_status()
except requests.exceptions.HTTPError as error:
    print('HTTP error:', error)
except requests.exceptions.Timeout:
    print('Request timed out')
except requests.exceptions.ConnectionError:
    print('Connection error')

Для неверных учетных данных GitHub возвращает код 401. При таком ответе вывод начнется с двух строк:

401
HTTP error: 401 Client Error

После Client Error Requests добавит описание ошибки и URL.

Итоговый шаблон GET-запроса

Функция объединяет URL, параметры, заголовки, таймаут, проверку статуса и разбор JSON. Замените значения url и params данными своего API.

import requests


def get_json(url, params=None, token=None):
    headers = {
        'User-Agent': 'python-requests-example',
        'Accept': 'application/json',
    }
    if token:
        headers['Authorization'] = f'Bearer {token}'

    try:
        res = requests.get(
            url,
            params=params,
            headers=headers,
            timeout=10,
        )
        res.raise_for_status()
    except requests.exceptions.HTTPError as error:
        print(f'HTTP error {res.status_code}: {error}')
        return None
    except requests.exceptions.Timeout:
        print('Request timed out')
        return None
    except requests.exceptions.ConnectionError:
        print('Connection error')
        return None

    return res.json()


data = get_json(
    'https://api.github.com',
)
if data:
    print(data['current_user_url'])

Сохраните шаблон в script.py и запустите python script.py. При успешном ответе функция вернет словарь, а программа напечатает адрес https://api.github.com/user.

Шаблон подходит для API с JSON-ответом. Если сервер возвращает HTML или файл, замените res.json() на обработку res.text или res.content. Некорректный JSON вызовет ошибку разбора даже при статусе 200.

GET и POST: в чем разница

GET получает ресурс и передает параметры через params. POST отправляет данные в теле запроса, например JSON в аргументе json.

Вызов requests.post(url, json={'name': 'Book'}, timeout=10) отправит объект JSON на адрес url. Адрес и допустимые поля задает документация конкретного API. Поисковые параметры в URL могут сопровождать оба метода.

Что проверить перед запуском скрипта

• Среда. Виртуальное окружение активировано, а команда pip install requests завершилась без ошибки.
• Запрос. URL передан в requests.get(), параметры лежат в params, а заголовки – в headers.
• Надежность. Вызов содержит timeout, после запроса стоит raise_for_status(), а сетевые исключения перехватываются.
• Данные. Код вызывает res.json() только для JSON-ответа и обращается к существующему ключу.

Официальная документация Requests содержит раздел Quickstart с примерами params, заголовков и обработки ответа. Справочник API описывает аргументы requests.get() и свойства Response.

Совет от нашей редакции: начинайте работу с API без токена, если endpoint это разрешает. Получите успешный ответ и нужное поле, затем добавляйте авторизацию.