Generating Statistics

The Shodan API makes it possible to get a distribution of values for a property using a concept called facets. A facet is typically named after a matching property and lets you see how many results there are for a given property value. Filters let you narrow down search results while facets let you see the big picture of the results. For example, to get a breakdown of the top 10 countries with the most web servers you would use a search query of HTTP and ask the API to facet on country.

The left sidebar of the Shodan search results is created using facets. And the entire Internet Exposure website is powered by a free API key that runs facet queries:

Shodan Internet Exposure Dashboard

You can explore the list of available facets from our Facet Analysis page.

Everything on this page can be done with a free API key


Usage: shodan stats [OPTIONS] <search query>

  Provide summary information about a search query

  --limit INTEGER      The number of results to return.
  --facets TEXT        List of facets to get statistics for.
  -O, --filename TEXT  Save the results in a CSV file of the provided name.
  -h, --help           Show this message and exit.

The stats command is the primary way to perform facet queries in Shodan. If you only give it a search query then it will automatically facet on a few popular properties such as org and port. The real advantage of the CLI however is that you have complete control over the facets so lets see how to create our own facet queries.

The --facets is how you define the list of facets that you want to get information about. Multiple values can be provided by giving a comma-separated list of values. For example, the below command gets a breakdown of the top 10 ports that SSH runs on:

$ shodan stats --facets port ssh

ssh is the search query. We are using the port facet to get a breakdown of the port property. And by default, the stats command will return the top 10 values of a facet.

Lets also learn which organizations are running most of the SSH services:

$ shodan stats --facets port,org ssh

We are faceting on both port and org. The search query is still ssh.

Optionally, you can specify how many facet values you would like to see by adding a :<number> after the facet name. For example, lets get a breakdown of the top 100 ports that SSH is running on:

$ shodan stats --facets port:100 ssh

And you can have different limits for each facet:

$ shodan stats --facets port:100,org:20 ssh

The above would get a breakdown of the top 100 ports and the top 20 organizations that are running SSH. And of course you can combine facets and filters to get more interesting breakdowns. For example, here is a list of the top 50 cities in the U.S. that are running SSH:

$ shodan stats --facets city:50 ssh country:US
Next: Configure Network Monitoring