Python requests.head Function

The requests.head function in Python’s requests module is used to make HTTP HEAD requests.

This function is similar to a GET request, but it only retrieves the headers and not the actual content of the resource.

It is typically used to check the status, content type, and other meta information about a resource.

Table of Contents

1. Introduction
2. requests.head Function Syntax
3. Examples
   • Basic Usage
   • Using Query Parameters
   • Sending Headers
   • Handling Responses
4. Real-World Use Case
5. Conclusion

Introduction

The requests.head function is part of the requests module, which makes it easy to make HTTP requests in Python. You can use this function to send a HEAD request to a web server to retrieve the headers of a resource.

requests.head Function Syntax

Here’s how you use the requests.head function:

import requests

response = requests.head(url, **kwargs)

Parameters:

• url: The URL for the request.
• **kwargs: Optional arguments to customize the request. Common ones include:
  • params: Dictionary to send in the query string.
  • headers: Dictionary of HTTP headers to send with the request.

Returns:

• A Response object containing the server’s response to the HTTP request.

Examples

Basic Usage

Send a simple HEAD request to a URL.

import requests

response = requests.head('https://jsonplaceholder.typicode.com/posts/1')
print(response.headers)

Output:

{'Date': 'Fri, 26 Jul 2024 09:30:43 GMT', 'Content-Type': 'application/json; charset=utf-8', 'Connection': 'keep-alive', 'Report-To': '{"group":"heroku-nel","max_age":3600,"endpoints":[{"url":"https://nel.heroku.com/reports?ts=1710182097&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=fKdm2T1w7s0rUdsgIrKaxbRXRbknGQ7IQ6jA1AWeziU%3D"}]}', 'Reporting-Endpoints': 'heroku-nel=https://nel.heroku.com/reports?ts=1710182097&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=fKdm2T1w7s0rUdsgIrKaxbRXRbknGQ7IQ6jA1AWeziU%3D', 'Nel': '{"report_to":"heroku-nel","max_age":3600,"success_fraction":0.005,"failure_fraction":0.05,"response_headers":["Via"]}', 'X-Powered-By': 'Express', 'X-Ratelimit-Limit': '1000', 'X-Ratelimit-Remaining': '999', 'X-Ratelimit-Reset': '1710182100', 'Vary': 'Origin, Accept-Encoding', 'Access-Control-Allow-Credentials': 'true', 'Cache-Control': 'max-age=43200', 'Pragma': 'no-cache', 'Expires': '-1', 'X-Content-Type-Options': 'nosniff', 'Etag': 'W/"124-yiKdLzqO5gfBrJFrcdJ8Yq0LGnU"', 'Via': '1.1 vegur', 'CF-Cache-Status': 'HIT', 'Age': '20786', 'Server': 'cloudflare', 'CF-RAY': '8a935f653fcc9993-CDG', 'Content-Encoding': 'gzip', 'alt-svc': 'h3=":443"; ma=86400'}

Using Query Parameters

Send a HEAD request with query parameters.

import requests

params = {'userId': 1}
response = requests.head('https://jsonplaceholder.typicode.com/posts', params=params)
print(response.headers)

Output:

{'Date': 'Fri, 26 Jul 2024 09:30:44 GMT', 'Content-Type': 'application/json; charset=utf-8', 'Connection': 'keep-alive', 'Report-To': '{"group":"heroku-nel","max_age":3600,"endpoints":[{"url":"https://nel.heroku.com/reports?ts=1719314457&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=s4aFYFBKlbxW6BwLguMyEWJKeLVMOFePPZ%2BgapuESME%3D"}]}', 'Reporting-Endpoints': 'heroku-nel=https://nel.heroku.com/reports?ts=1719314457&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=s4aFYFBKlbxW6BwLguMyEWJKeLVMOFePPZ%2BgapuESME%3D', 'Nel': '{"report_to":"heroku-nel","max_age":3600,"success_fraction":0.005,"failure_fraction":0.05,"response_headers":["Via"]}', 'X-Powered-By': 'Express', 'X-Ratelimit-Limit': '1000', 'X-Ratelimit-Remaining': '999', 'X-Ratelimit-Reset': '1719314466', 'Vary': 'Origin, Accept-Encoding', 'Access-Control-Allow-Credentials': 'true', 'Cache-Control': 'max-age=43200', 'Pragma': 'no-cache', 'Expires': '-1', 'X-Content-Type-Options': 'nosniff', 'Etag': 'W/"aa6-j2NSH739l9uq40OywFMn7Y0C/iY"', 'Content-Encoding': 'gzip', 'Via': '1.1 vegur', 'CF-Cache-Status': 'HIT', 'Age': '4752', 'Server': 'cloudflare', 'CF-RAY': '8a935f69fac9153a-CDG', 'alt-svc': 'h3=":443"; ma=86400'}

Sending Headers

Send custom headers with a HEAD request.

import requests

headers = {'Authorization': 'Bearer your_token'}
response = requests.head('https://jsonplaceholder.typicode.com/posts/1', headers=headers)
print(response.headers)

Output:

{'Date': 'Fri, 26 Jul 2024 09:30:44 GMT', 'Content-Type': 'application/json; charset=utf-8', 'Connection': 'keep-alive', 'Report-To': '{"group":"heroku-nel","max_age":3600,"endpoints":[{"url":"https://nel.heroku.com/reports?ts=1710182097&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=fKdm2T1w7s0rUdsgIrKaxbRXRbknGQ7IQ6jA1AWeziU%3D"}]}', 'Reporting-Endpoints': 'heroku-nel=https://nel.heroku.com/reports?ts=1710182097&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=fKdm2T1w7s0rUdsgIrKaxbRXRbknGQ7IQ6jA1AWeziU%3D', 'Nel': '{"report_to":"heroku-nel","max_age":3600,"success_fraction":0.005,"failure_fraction":0.05,"response_headers":["Via"]}', 'X-Powered-By': 'Express', 'X-Ratelimit-Limit': '1000', 'X-Ratelimit-Remaining': '999', 'X-Ratelimit-Reset': '1710182100', 'Vary': 'Origin, Accept-Encoding', 'Access-Control-Allow-Credentials': 'true', 'Cache-Control': 'max-age=43200', 'Pragma': 'no-cache', 'Expires': '-1', 'X-Content-Type-Options': 'nosniff', 'Etag': 'W/"124-yiKdLzqO5gfBrJFrcdJ8Yq0LGnU"', 'Via': '1.1 vegur', 'CF-Cache-Status': 'HIT', 'Age': '20787', 'Server': 'cloudflare', 'CF-RAY': '8a935f6edb540411-CDG', 'Content-Encoding': 'gzip', 'alt-svc': 'h3=":443"; ma=86400'}

Handling Responses

Send a HEAD request and handle the response headers.

import requests

response = requests.head('https://jsonplaceholder.typicode.com/posts/1')
if response.status_code == 200:
    print('Resource exists')
else:
    print('Resource does not exist')

Output:

Resource exists

Real-World Use Case

Checking Resource Availability

Check if a resource is available on a server without downloading the entire content.

import requests

url = 'https://jsonplaceholder.typicode.com/posts/1'
response = requests.head(url)
if response.status_code == 200:
    print('Resource is available')
    print('Headers:', response.headers)
else:
    print('Resource is not available')

Output:

Resource is available
Headers: {'Date': 'Fri, 26 Jul 2024 09:30:46 GMT', 'Content-Type': 'application/json; charset=utf-8', 'Connection': 'keep-alive', 'Report-To': '{"group":"heroku-nel","max_age":3600,"endpoints":[{"url":"https://nel.heroku.com/reports?ts=1710182097&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=fKdm2T1w7s0rUdsgIrKaxbRXRbknGQ7IQ6jA1AWeziU%3D"}]}', 'Reporting-Endpoints': 'heroku-nel=https://nel.heroku.com/reports?ts=1710182097&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=fKdm2T1w7s0rUdsgIrKaxbRXRbknGQ7IQ6jA1AWeziU%3D', 'Nel': '{"report_to":"heroku-nel","max_age":3600,"success_fraction":0.005,"failure_fraction":0.05,"response_headers":["Via"]}', 'X-Powered-By': 'Express', 'X-Ratelimit-Limit': '1000', 'X-Ratelimit-Remaining': '999', 'X-Ratelimit-Reset': '1710182100', 'Vary': 'Origin, Accept-Encoding', 'Access-Control-Allow-Credentials': 'true', 'Cache-Control': 'max-age=43200', 'Pragma': 'no-cache', 'Expires': '-1', 'X-Content-Type-Options': 'nosniff', 'Etag': 'W/"124-yiKdLzqO5gfBrJFrcdJ8Yq0LGnU"', 'Via': '1.1 vegur', 'CF-Cache-Status': 'HIT', 'Age': '20789', 'Server': 'cloudflare', 'CF-RAY': '8a935f796b8b3cb7-CDG', 'Content-Encoding': 'gzip', 'alt-svc': 'h3=":443"; ma=86400'}

Conclusion

The requests.head function is a simple and effective way to make HTTP HEAD requests in Python. You can use it to retrieve headers from web servers, include query parameters and custom headers, and handle responses. This function makes it easy to interact with web services and check the status and meta-information of resources without downloading all the content.