How to Use Shodan’s Python SDK for Device Discovery and Analysis

Preparation

Install Python and pip on your system. Anaconda can be used as an all‑in‑one distribution. Install the Shodan Python client:

pip install shodan

Obtain API key

Register a free account at https://account.shodan.io/register, confirm the email, and copy the API key shown on the dashboard. The key is required for all API calls.

Basic search with the Python SDK

from shodan import Shodan

api = Shodan('YOUR_API_KEY')

def search_shodan(keyword):
    result = api.search(keyword)
    for service in result['matches']:
        print(service['ip_str'])

search_shodan("Hikvision-Webs")

The call returns a list of IP addresses and the ports they expose (e.g., 17, 80, 111, 995, 3128, 5000, 6000, 20547).

Facets (aggregated statistics)

Facets allow aggregation of fields such as organization, domain, port, ASN, and country. The example below queries the same keyword and prints summaries for each facet.

from shodan import Shodan

api = Shodan('YOUR_API_KEY')

def try_facets(query):
    FACETS = [
        'org',
        'domain',
        'port',
        'asn',
        ('country', 3),
    ]
    FACET_TITLES = {
        'org': 'Top 5 Organizations',
        'domain': 'Top 5 Domains',
        'port': 'Top 5 Ports',
        'asn': 'Top 5 Autonomous Systems',
        'country': 'Top 3 Countries',
    }
    try:
        # count() is faster and does not require a paid plan
        result = api.count(query, facets=FACETS)
        print('Shodan Summary Information')
        print('Query: %s' % query)
        print('Total Results: %s
' % result['total'])
        for facet in result['facets']:
            print(FACET_TITLES[facet])
            for term in result['facets'][facet]:
                print('%s: %s' % (term['value'], term['count']))
    except Exception as e:
        print('Error: %s' % e)

try_facets("Hikvision-Webs")

Typical output shows the top three countries (e.g., United States, Japan, Germany) where the queried device type appears.

Limitations

Free API keys support only simple keyword searches. Advanced filters such as country:"US" require a paid plan.

Security note

Exposed services listed by Shodan can be targeted by attackers. Mitigate risk by changing default passwords, using strong credentials, and restricting management interfaces from the public Internet.