Advanced PHP5 REST API for
Switch branches/tags
Nothing to show
Clone or download



Lean and easily extendible PHP API for, supporting both the free API and the paid one. Requests are auto-generated by structure that defines the API protocol.

Authors and License

Shodan-PHP-REST-API is licensed under the GNU GPL v3 and is a project sponsored by ISGroup SRL and authored by Alex Salvetti and Francesco ascii Ongaro. This software is currently used by ScadaExposure, a permanent observatory on the exposure of ICS and SCADA devices on the Internet, to generate it's datasets.


  • Search Shodan.
  • Streaming API support for real-time consumption of Shodan data.
  • Exploit search API fully implemented.


  • Shodan.php is the API class: costants, shodan methods and the generation of the HTTP requests are defined here.
  • The script uses PHP magic methods (
  • shodan-api.php is the CLI interface, allowing to run differents commands; it also provides an how-to function.
  • Our API implementation uses 3 different base URLs: Shodan API, Streaming API and Exploits API.
  • Tests folder provides some examples on how to write your own search query, use the CLI -r flag for running them all or call one with the -t flag.
  • If you're in search of better and more thorough documentation, please refer to Shodan's REST API documentation (
  • For Shodan EXPLOITS API refer to the documentation (
  • For Shodan STREAM API refer to the documentation (


You can implement the class API directly in your code or experiment with the CLI. In both cases you'll need to change your API KEY in shodan-api.php or anywhere you istantiate the API object:

$key = 'Insert your API key here';

Following are the options:

Short form Long form Variables
-r --run-tests
-t --run-test STRING
-m --method ShodanHost --ip STRING [--history BOOLEAN] [--minify BOOLEAN]
-m --method ShodanHostCount --query STRING [--facets STRING]
-m --method ShodanHostSearch --query STRING [--facets STRING]
-m --method ShodanHostSearchTokens --query STRING
-m --method ShodanPorts
-m --method ShodanProtocols
-m --method ShodanScan --ips STRING
-m --method ShodanScanInternet --port INTEGER --protocol STRING
-m --method ShodanScan_Id --id STRING
-m --method ShodanServices
-m --method ShodanQuery [--page INTEGER] [--sort STRING] [--order STRING]
-m --method ShodanQuerySearch --query STRING [--page INTEGER]
-m --method ShodanQueryTags [--size INTEGER]
-m --method LabsHoneyscore --ip STRING
-m --method Search --query STRING [--facets STRING] [--page INTEGER]
-m --method Count --query STRING [--facets STRING]
-m --method ShodanBanners
-m --method ShodanAsn --asn STRING
-m --method ShodanCountries --countries STRING
-m --method ShodanPorts_Stream --ports STRING

Some CLI Run Examples

Showing usage options:


Shodan Host method on Facebook ip:


Shodan Scan request on some ips:


Shodan Scan request status:


Handle overlapping methods

Using PHP magic methods we call the method by its name and use it for generate the URL for the request. For doing that we use preg_replace inserting a / when an uppercase character is found and appending that character in lowercase.

But we found that two methods in Shodan API were overlapping with other two methods, that are: "ShodanScan" and "ShodanPorts". So we renamed "ShodanScan" given with "id" parameter in "ShodanScan_Id", and "ShodanPorts" for the stream API in "ShodanPorts_Stream".

But the URL must not have those renaming, so we eliminate the _ and all it comes next of it for getting the job done.

You can find it at:

Tests class - REST API

Shodan Host (/tests/ip.php):

Return all services that have been found on the given host IP.

	'ip' => '', //

Shodan Host Count (/tests/count.php):

Returns the total number of results that matched the query and any facet information that was requested.

  'query' => 'Niagara Web Server',

Shodan Host Search (/tests/search.php):

Search Shodan using the same query syntax as the website and use facets to get summary information for different properties. - This method may use API query credits depending on usage.

	'query' => 'Niagara Web Server',

Shodan Host Search Tokens (/tests/search.php):

This method lets you determine which filters are being used by the query string and what parameters were provided to the filters.

	'query' => 'Niagara Web Server country:"IT"',

Shodan Ports (/tests/ports.php):

This method returns a list of port numbers that the crawlers are looking for.


Shodan Protocols (/tests/protocols.php):

This method returns an object containing all the protocols that can be used when launching an Internet scan.


Shodan Scan (/tests/crawl.php):

Use this method to request Shodan to crawl a network. - POST METHOD REQUIRE PAID API KEY.

	'ips' => '',

Shodan Scan Internet (/tests/crawl.php):

Use this method to request Shodan to crawl the Internet for a specific port. - POST METHOD REQUIRE PAID API KEY AND SHODAN PERMISSION.

	'port' => '80',
	'protocol' => 'dns-tcp',

Shodan Scan Id (/tests/crawl.php):

Check the progress of a previously submitted scan request.

	'id' => 'R2XRT5HH6X67PFAB',

Shodan Services (/tests/crawl.php):

This method returns an object containing all the services that the Shodan crawlers look at. It can also be used as a quick and practical way to resolve a port number to the name of a service.


Shodan Query (/tests/saved_query.php):

Use this method to obtain a list of search queries that users have saved in Shodan.

	'page' => '1', 

Shodan Query (/tests/saved_query.php):

Use this method to search the directory of search queries that users have saved in Shodan.

	'query' => 'fax',

Shodan Query Tags (/tests/query_tags.php):

Use this method to obtain a list of popular tags for the saved search queries in Shodan.

	'size' => '30',

Tests class - Esperimental method

Labs Honeyscore (/tests/honeypot.php):

Calculates a honeypot probability score ranging from 0 (not a honeypot) to 1.0 (is a honeypot).

	'ip' => '', //

Tests class - Exploits REST API

Search Exploits (/tests/exploits.php):

Search across a variety of data sources for exploits and use facets to get summary information.

	'query' => 'cve',

Count Exploits (/tests/exploits.php):

This method behaves identical to the "/search" method with the difference that it doesn't return any results.

	'query' => 'cve',