How To Get Started With the Requests Library in Python

Introduction

This python requests tutorial explains how to send HTTP requests from Python using the popular requests library. You’ll learn the basics of GET and POST requests, how to inspect response status codes and headers, parse JSON payloads, and pass query parameters. The examples are practical for interacting with REST APIs, so you can apply them when building integrations or working with third-party services.

Note: some live API examples in guides use third-party API keys. Availability of free keys can change, so treat those examples as educational rather than guaranteed working credentials.

Prerequisites

• Python 3 installed locally.
• Optional but recommended: a virtual environment for your project.
• The requests package for Python. Install with:

pip install requests

What is an HTTP request?

HTTP requests are how clients (browsers, scripts, apps) communicate with servers over the web. A client sends a request to a URL and the server responds with a status code, headers, and a body. Typical request methods are GET (read data), POST (create or submit data), and PUT/PATCH (update data).

Quick start: first python requests example

Here is a minimal python requests get example. Save it as example.py and run it to see the response object and status.

import requests

response = requests.get('https://www.example.com')
print(response)            # e.g. <Response [200]>
print(response.status_code)

This demonstrates how to make a simple HTTP GET with the requests library python developers commonly use for scripting and API calls.

Checking status codes

HTTP status codes indicate the outcome of a request. Typical ranges:

• 1xx — Informational
• 2xx — Success (200 is common)
• 3xx — Redirects
• 4xx — Client errors (404 = Not Found)
• 5xx — Server errors (500 = Internal Server Error)

You can test success like this:

if response.ok:
    print('Request succeeded')
else:
    print('Request failed', response.status_code)

Inspecting response headers

The response.headers property is a dictionary-like object that contains metadata about the response, including content type, caching rules, and server info. Example:

print(response.headers.get('Content-Type'))

Knowing the content type helps decide whether to use response.text or response.json() when handling the body.

Reading the response body

For textual responses (HTML, plain text) use response.text. For JSON APIs, requests can parse the JSON into Python structures:

# HTML / plain text
print(response.text[:500])  # preview first 500 characters

# JSON response
api_resp = requests.get('https://api.example.com/data')
if api_resp.headers.get('Content-Type','').startswith('application/json'):
    data = api_resp.json()    # dict / list
    print(data)

Passing query parameters (params)

Rather than concatenating parameters into the URL, pass a params dictionary. This is the recommended way to build GET queries with python http requests.

params = {'q': 'python requests tutorial', 'page': 1}
search = requests.get('https://api.example.com/search', params=params)
print(search.url)   # URL with encoded query string
print(search.status_code)

Sending data with POST

To send data to an API endpoint, use requests.post. You can send form-encoded data or JSON payloads. Example:

# Form-encoded
payload = {'username': 'alice', 'password': 'secret'}
resp = requests.post('https://api.example.com/login', data=payload)

# JSON body
resp_json = requests.post('https://api.example.com/items', json={'name':'notebook', 'price':9.99})

Handling timeouts and simple retries

Always set a timeout to avoid hanging requests. For basic retry behavior, implement a retry loop or use requests.adapters with urllib3 Retry. Here is a straightforward retry loop:

import time

def get_with_retries(url, attempts=3, timeout=5):
    for i in range(attempts):
        try:
            r = requests.get(url, timeout=timeout)
            r.raise_for_status()
            return r
        except requests.RequestException as e:
            if i == attempts - 1:
                raise
            time.sleep(2 ** i)  # exponential backoff

result = get_with_retries('https://api.example.com/resource')

Example: calling a translation API with params and JSON

Below is a generic pattern showing how to call a translation-style API with query parameters and then parse the JSON response. Replace API_KEY and endpoint with your provider details.

API_KEY = 'your_api_key_here'
endpoint = 'https://api.translate.example/translate'
params = {
    'key': API_KEY,
    'text': 'Hello',
    'lang': 'en-es'
}
resp = requests.get(endpoint, params=params, timeout=10)
if resp.ok:
    payload = resp.json()
    # payload might be {'code':200, 'lang':'en-es', 'text':['Hola']}
    translated = payload.get('text', [None])[0]
    print(translated)
else:
    print('Translate API error', resp.status_code)

Remember that API keys should be kept secret. Netalith not hard-code keys in public repositories.

Checking response status codes in detail

Sometimes APIs return helpful error codes or messages in the response body. Use response.status_code to branch logic and response.json() to extract error details when content type is JSON.

Best practices and next steps

• Prefer requests.get(..., params=...) and requests.post(..., json=...) over manual string concatenation.
• Always set timeouts and handle exceptions from requests to build resilient python api requests.
• Log request URLs and status codes for debugging, but never log secrets like API keys.
• For production-grade retry behavior, use requests.adapters.HTTPAdapter with urllib3.util.retry.Retry.

Conclusion

This python requests tutorial covered how to use the requests library python developers rely on for HTTP interactions: installing with pip install requests, making GET and POST requests, inspecting status codes and headers, parsing JSON responses, and basic timeout and retry techniques. Use these patterns as a foundation for working with REST APIs and integrating third-party services into your applications.