Python requests library: How to set params

Introduction

Working with HTTP requests is a core part of many web-based Python projects. The requests library simplifies this process, including how to craft queries with parameters.

Basic Usage of Params

Sending a GET request with query parameters is a common operation. Here’s how to add parameters to your requests:

import requests

params = {'q': 'python', 'sort': 'relevance'}
response = requests.get('https://api.example.com/search', params=params)
print(response.url)

This will send a request to https://api.example.com/search?q=python&sort=relevance.

Passing Lists as Parameters

Sometimes you may need to send a list of items as part of your query params:

params = {'tags': ['python', 'tutorial']}
response = requests.get('https://api.example.com/articles', params=params)
print(response.url)

The requests library correctly interprets the list and formats the URL as https://api.example.com/articles?tags=python&tags=tutorial.

Advanced Parameter Encoding

When you need to send complex data as query parameters, you may need to encode them:

from requests.utils import requote_uri

params = {'date': '2023/04/01'}
encoded_params = requote_uri(params)
response = requests.get(f'https://api.example.com/events?{encoded_params}')
print(response.url)

This approach ensures special characters are correctly encoded in the URL.

Different Types of Parameter Values

The requests library can handle a variety of parameter types:

params = {
    'boolean': True,
    'none': None,
    'number': 5
}
response = requests.get('https://api.example.com/filter', params=params)
print(response.url)

In the resulting URL, Python’s True becomes true, None is ignored, and numbers are converted to strings.

Session Objects for Parameter Persistence

To reuse parameters across requests, use a session object:

with requests.Session() as session:
    session.params = {'api_key': 'MY_API_KEY'}
    response = session.get('https://api.example.com/private/data')
    print(response.url)

This keeps you from having to send the API key with every single request.

Error Handling with Params

It’s important to handle errors that may occur when bad parameters are sent:

try:
    response = requests.get('https://api.example.com/data', params={'limit': 'ten'})
    response.raise_for_status()
except requests.exceptions.HTTPError as err:
    print(f'HTTP Error: {err}')
except requests.exceptions.RequestException as e:
    print(f'Request Exception: {e}')

This helps in debugging and providing user feedback.

Using Params with POST Requests

Query parameters can also be used with POST requests, but it’s more common to send data in the body of the request:

data = {'username': 'user', 'password': 'pass'}
response = requests.post('https://api.example.com/session', data=data)
print(response.status_code)

Remember, using GET requests for sensitive data like passwords is not recommended.

Conclusion

Incorporating query parameters into the requests you send out is an integral part of interacting with web APIs and other HTTP services. Mastering the requests library’s parameter options equips you with a potent tool to make precise and complex HTTP requests with ease. Be sure to also prioritize security and efficiency as you work with web requests in Python.