Shodan Python Library

1.31.0 · active · verified Thu Apr 16

The Shodan Python library provides a comprehensive wrapper around the Shodan REST API and the experimental Streaming API, allowing developers to programmatically access information about Internet-connected devices, search for exploits, perform bulk IP lookups, and consume real-time Shodan data. Version 1.31.0 is the latest release, with updates released periodically to add new features and handle API changes.

Common errors

```
AttributeError: 'module' object has no attribute 'Shodan'
```
cause A Python script in your working directory is named `shodan.py`, creating a name conflict with the installed `shodan` library.

fix Rename your Python script file to something other than `shodan.py` (e.g., `my_shodan_script.py`).
```
shodan.exception.APIError: Access denied
```
cause The API key provided does not have the necessary permissions or subscription level to access the requested Shodan resource (e.g., Streaming API, Bulk Data API, Shodan Monitor).

fix Ensure your Shodan API key is correct and has an active subscription plan that includes access to the specific API feature you are trying to use. Check your Shodan account settings.
```
shodan.exception.APIError: The search request timed out or your query was invalid. OR shodan.exception.APIError: Unable to parse JSON response
```
cause This error can stem from several issues: exceeding API rate limits, providing an improperly formatted or invalid search query, or encountering temporary API service issues.

fix Verify your search query against Shodan's documentation. If performing multiple requests, implement rate-limiting or exponential backoff. Check the Shodan status page for service outages.
```
IOError: [Errno 9] Bad file descriptor (when running CLI) OR issues with ANSI escape sequences/colored output.
```
cause This typically occurs when running the `shodan` command-line interface in older Windows Command Prompt environments that lack full support for ANSI escape sequences used for colored output.

fix Use a more modern terminal application like Windows Terminal, PowerShell, or a compatible Linux/macOS terminal. Ensure the `colorama` library (a dependency for CLI color support) is correctly installed in your environment.

Warnings

deprecated Older documentation and examples may suggest installing with `easy_install`. This method is deprecated and `pip` should be used instead.
Fix: Always use `pip install shodan` for installation and upgrades.
gotcha Access to certain advanced features (e.g., Streaming API, Shodan Monitor vulnerability whitelisting, custom data streams, Bulk Data API) requires a paid Shodan API plan. A free developer API key will result in 'Access denied' errors for these features.
Fix: Review Shodan's pricing and upgrade your API plan if needed to access restricted features.
gotcha The Shodan API implements rate limiting, typically allowing 1 request per second with some bursting. Exceeding this limit will cause `APIError` exceptions.
Fix: Implement proper error handling with exponential backoff for retries, or introduce delays between successive API calls, especially in loops.

Install

pip install shodan Install latest version

Imports

Shodan
wrong:
```
import shodan; api = shodan.Shodan()
```
correct:
```
from shodan import Shodan
```
While 'import shodan' followed by 'shodan.Shodan()' works, 'from shodan import Shodan' is the idiomatic way to import the main class.

Quickstart

This quickstart initializes the Shodan API client using an API key (preferably from an environment variable), retrieves the user's IP, performs a basic search for 'apache' servers, and looks up information for a specific IP address. It includes basic error handling for API-specific exceptions.

import os
from shodan import Shodan
from shodan.exception import APIError

SHODAN_API_KEY = os.environ.get('SHODAN_API_KEY', 'YOUR_SHODAN_API_KEY')

if not SHODAN_API_KEY or SHODAN_API_KEY == 'YOUR_SHODAN_API_KEY':
    print("Please set the SHODAN_API_KEY environment variable or replace 'YOUR_SHODAN_API_KEY'.")
else:
    try:
        api = Shodan(SHODAN_API_KEY)

        # Lookup your current IP address information
        my_ip_info = api.tools.myip()
        print(f"Your IP: {my_ip_info}")

        # Search for servers running Apache
        results = api.search('apache')
        print(f"Results found for 'apache': {results['total']}")
        for result in results['matches']:
            print(f"  IP: {result['ip_str']}, Port: {result['port']}, Org: {result['org']}")
            break # Print only the first result for brevity

        # Lookup a specific host (e.g., Google DNS)
        host_info = api.host('8.8.8.8')
        print(f"\nHost 8.8.8.8 info: {host_info['country_name']}, {host_info['org']}")

    except APIError as e:
        print(f"Error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →