If you have an API plan then you get a certain number of query credits that you can spend each month. For people with the Shodan Membership that means you get 100 query credits per month while for the API plans it can range from 10,000 up to unlimited.

1 query credit = 100 results

Every query credit gets you up to 100 results, which means that you can download at least 10,000 results every month - regardless of the type of search you're performing.

Using the Command-Line Tool

The Shodan CLI provides a command to easily download data using the query credits from your API. Here's a quick video that shows how it works in action:

The basics of it are:

shodan download --limit <number of results> <filename> <search query>

For example, this is the command to download 500 results for the search query "product:mongodb" which returns Internet-facing MongoDB services:

shodan download --limit 500 mongodb-results product:mongodb

The results of the above command will be saved in a file called mongodb-results.json.gz. At this point, you can easily convert the file into CSV, KML or simply output a list of IP:port pairs by using the shodan parse command:

shodan parse --fields ip_str,port --separator , mongodb.json.gz

Programming with the Shodan API

The CLI should work for most people but sometimes you want to perform custom transformations on the banners as you're downloading them. Or you don't want to store the information in a local file. In those cases, you can use a convenient helper method provided by the Python library for Shodan called search_cursor() to iterate over the results:

import shodan

api = shodan.Shodan('Your API key')

limit = 500
counter = 0
for banner in api.search_cursor('product:mongodb'):
    # Perform some custom manipulations or stream the results to a database
    # For this example, I'll just print out the "data" property
    print(banner['data'])

    # Keep track of how many results have been downloaded so we don't use up all our query credits
    counter += 1
    if counter >= limit:
        break