ShodanDeveloper


API Reference

API Documentation

  1. Requirements
  2. Introduction
  3. Clients
  4. REST API Documentation
  5. Streaming API Documentation
  6. Trends API Documentation

Appendix

  1. Banner Specification
  2. Search Filters

REST API Documentation

The base URL for all of these methods is: 
https://api.shodan.io

SearchMethods

GET/shodan/host/{ip}
Host Information

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

Request URL 
https://api.shodan.io/shodan/host/{ip}?key={YOUR_API_KEY}

Parameters
  • ip: [String] Host IP address
  • history (optional): [Boolean] True if all historical banners should be returned (default: False)
  • minify (optional): [Boolean] True to only return the list of ports and the general host information, no banners. (default: False)
Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/host/8.8.8.8?key={YOUR_API_KEY}"
Response 
{
    "region_code": null,
    "ip": 134744072,
    "postal_code": null,
    "country_code": "US",
    "city": null,
    "dma_code": null,
    "last_update": "2021-01-22T08:49:35.190817",
    "latitude": 37.751,
    "tags": [],
    "area_code": null,
    "country_name": "United States",
    "hostnames": [
        "dns.google"
    ],
    "org": "Google",
    "data": [
        {
            "_shodan": {
                "id": "cea5795b-55fd-4595-b9e5-ad5ca847cb4b",
                "options": {},
                "ptr": true,
                "module": "dns-udp",
                "crawler": "ac284849be0745621b3c518f74c14cf43cafbf08"
            },
            "hash": -553166942,
            "os": null,
            "opts": {
                "raw": "34ef818200010000000000000776657273696f6e0462696e640000100003"
            },
            "ip": 134744072,
            "isp": "Google",
            "port": 53,
            "hostnames": [
                "dns.google"
            ],
            "location": {
                "city": null,
                "region_code": null,
                "area_code": null,
                "longitude": -97.822,
                "country_code3": null,
                "country_name": "United States",
                "postal_code": null,
                "dma_code": null,
                "country_code": "US",
                "latitude": 37.751
            },
            "dns": {
                "resolver_hostname": null,
                "recursive": true,
                "resolver_id": null,
                "software": null
            },
            "timestamp": "2021-01-22T08:49:35.190817",
            "domains": [
                "dns.google"
            ],
            "org": "Google",
            "data": "\nRecursion: enabled",
            "asn": "AS15169",
            "transport": "udp",
            "ip_str": "8.8.8.8"
        }
    ],
    "asn": "AS15169",
    "isp": "Google",
    "longitude": -97.822,
    "country_code3": null,
    "domains": [
        "dns.google"
    ],
    "ip_str": "8.8.8.8",
    "os": null,
    "ports": [
        53
    ]
}
Request 
$ shodan host 8.8.8.8
Response 
8.8.8.8
Hostnames:               dns.google
Country:                 United States
Organization:            Google
Updated:                 2021-01-22T08:49:35.190817
Number of open ports:    1

Ports:
    53/udp
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.host('8.8.8.8'))
Response 
{
    "area_code": None,
    "asn": "AS15169",
    "city": None,
    "country_code": "US",
    "country_code3": None,
    "country_name": "United States",
    "data": [
        {
            "asn": "AS15169",
            "data": "\nRecursion: enabled",
            "dns": {
                "recursive": True,
                "resolver_hostname": None,
                "resolver_id": None,
                "software": None,
            },
            "domains": ["dns.google"],
            "hash": -553166942,
            "hostnames": ["dns.google"],
            "ip": 134744072,
            "ip_str": "8.8.8.8",
            "isp": "Google",
            "location": {
                "area_code": None,
                "city": None,
                "country_code": "US",
                "country_code3": None,
                "country_name": "United States",
                "dma_code": None,
                "latitude": 37.751,
                "longitude": -97.822,
                "postal_code": None,
                "region_code": None,
            },
            "opts": {
                "raw": "34ef818200010000000000000776657273696f6e0462696e640000100003"
            },
            "org": "Google",
            "os": None,
            "port": 53,
            "timestamp": "2021-01-22T08:49:35.190817",
            "transport": "udp",
        }
    ],
    "dma_code": None,
    "domains": ["dns.google"],
    "hostnames": ["dns.google"],
    "ip": 134744072,
    "ip_str": "8.8.8.8",
    "isp": "Google",
    "last_update": "2021-01-22T08:49:35.190817",
    "latitude": 37.751,
    "longitude": -97.822,
    "org": "Google",
    "os": None,
    "ports": [53],
    "postal_code": None,
    "region_code": None,
    "tags": [],
}
GET/shodan/host/count
Search Shodan without Results

This method behaves identical to "/shodan/host/search" with the only difference that this method does not return any host results, it only returns the total number of results that matched the query and any facet information that was requested. As a result this method does not consume query credits.

Request URL 
https://api.shodan.io/shodan/host/count?key={YOUR_API_KEY}&query={query}&facets={facets}

Parameters
  • query: [String] Shodan search query. The provided string is used to search the database of banners in Shodan, with the additional option to provide filters inside the search query using a "filter:value" format. For example, the following search query would find Apache Web servers located in Germany: "apache country:DE".
    List of Filters
  • facets (optional): [String] A comma-separated list of properties to get summary information on. Property names can also be in the format of "property:count", where "count" is the number of facets that will be returned for a property (i.e. "country:100" to get the top 100 countries for a search query). Visit the Shodan website's Facet Analysis page for an up-to-date list of available facets:
    Explore Facets
Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/host/count?key={YOUR_API_KEY}&query=port:22&facets=org,os"
Response 
{
    "matches": [],
    "facets": {
        "org": [
            {
                "count": 3012386,
                "value": "Amazon.com"
            },
            {
                "count": 1322102,
                "value": "Google Cloud"
            },
            {
                "count": 1075807,
                "value": "Digital Ocean"
            },
            {
                "count": 687155,
                "value": "OVH SAS"
            },
            {
                "count": 450521,
                "value": "Tencent cloud computing"
            }
        ],
        "os": [
            {
                "count": 601923,
                "value": "Ubuntu"
            },
            {
                "count": 227851,
                "value": "Debian"
            },
            {
                "count": 7660,
                "value": "Raspbian"
            }
        ]
    },
    "total": 19590274
}
Request 
$ shodan count port:22
Response 
19591483
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.count(query='port:22', facets='org,os'))
Response 
{
    "matches": [],
    "total": 19592093
}
GET/shodan/host/search
GET/shodan/host/search/facets
List all search facets

This method returns a list of facets that can be used to get a breakdown of the top values for a property.

Request URL 
https://api.shodan.io/shodan/host/search/facets?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/host/search/facets?key={YOUR_API_KEY}"
Response 
[
    'asn',
    'bitcoin.ip',
    'bitcoin.ip_count',
    ...
]
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.search_facets())
Response 
[
    "asn",
    "bitcoin.ip",
    "bitcoin.ip_count",
    ...
]
GET/shodan/host/search/filters
List all filters that can be used when searching

This method returns a list of search filters that can be used in the search query.

Request URL 
https://api.shodan.io/shodan/host/search/filters?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/host/search/filters?key={YOUR_API_KEY}"
Response 
[
    "all",
    "asn",
    "bitcoin.ip",
    "bitcoin.ip_count",
    ...
]
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.search_filters())
Response 
[
    "all",
    "asn",
    "bitcoin.ip",
    "bitcoin.ip_count",
    ...
]
GET/shodan/host/search/tokens
Break the search query into tokens

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

Request URL 
https://api.shodan.io/shodan/host/search/tokens?key={YOUR_API_KEY}&query={query}

Parameters
  • query: [String] Shodan search query. The provided string is used to search the database of banners in Shodan, with the additional option to provide filters inside the search query using a "filter:value" format. For example, the following search query would find Apache Web servers located in Germany: "apache country:DE".
    List of Filters

Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/host/search/tokens?key={YOUR_API_KEY}&query=Raspbian port:22"
Response 
{
    "attributes": {
        "ports": [22]
    },
    "errors": [],
    "string": "Raspbian",
    "filters": ["port"],
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.search_tokens(query='Raspbian port:22'))
Response 
{
    "attributes": {
        "ports": [22]
    },
    "errors": [],
    "string": "Raspbian",
    "filters": ["port"],
}

On-Demand Scanning

GET/shodan/ports
List all ports that Shodan is crawling on the Internet.

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

Request URL 
https://api.shodan.io/shodan/ports?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/ports?key={YOUR_API_KEY}"
Response 
[
    7,
    11,
    13,
    15,
    ...
]
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.ports())
Response 
[
    7,
    11,
    13,
    15,
    ...
]
GET/shodan/protocols
List all protocols that can be used when performing on-demand Internet scans via Shodan.

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

Request URL 
https://api.shodan.io/shodan/protocols?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/protocols?key={YOUR_API_KEY}"
Response 
{
    "afp": "AFP server information grabbing module",
    "ajp": "Check whether the Tomcat server running AJP protocol",
    "amqp": "Grab information from an AMQP service",
    ...
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.protocols())
Response 
{
    "afp": "AFP server information grabbing module",
    "ajp": "Check whether the Tomcat server running AJP protocol",
    "amqp": "Grab information from an AMQP service",
    ...
}
POST/shodan/scan
Request Shodan to crawl an IP/ netblock

Use this method to request Shodan to crawl a network.

Requirements

This method uses API scan credits: 1 IP consumes 1 scan credit. You must have a paid API plan (either one-time payment or subscription) in order to use this method.

Request URL 
https://api.shodan.io/shodan/scan?key={YOUR_API_KEY}
Parameters
  • ips: [String] A comma-separated list of IPs or netblocks (in CIDR notation) that should get crawled.
  • service: [Array] A list of services that should get scanned, where a service is defined as a [port, protocol].
Here is the JSON encoded object example (which allow to pass service variable to specify [port, protocol]) 
{
    "ips": {
        "{ips}": [
            {service},
            {service},
            ...
        ],
        ...
    }
}

Examples
Request (Scan all the services) 
$ curl -X POST "https://api.shodan.io/shodan/scan?key={YOUR_API_KEY}" -d 'ips=8.8.8.8,1.1.1.1'
Response 
{
    "count": 2,
    "id": "vwWO7P5N1rWF5jbh",
    "credits_left": 100000
}
Request (Scan specified services) 
$ curl -X POST "https://api.shodan.io/shodan/scan?key={YOUR_API_KEY}" -d 'ips={
    "1.1.1.1": [
        [53, "dns-udp"],
        [443, "https"]
    ]
}'
Response 
{
    "count": 1,
    "id": "z1ojEJbI0gy4AqSx",
    "credits_left": 100000
}
Request (Scan all the opened ports) 
$ shodan scan submit 8.8.8.8 1.1.1.1
Response 
Starting Shodan scan at 2021-01-26 15:58 - 100000 scan credits left

1.1.1.1 (one.one.one.one)
Country                  Australia
Organization             Mountain View Communications

Open Ports:
    53/udp
    80/tcp
    443/tcp
    |-- SSL Versions: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

8.8.8.8 (dns.google)
Country                  United States
Organization             Google

Open Ports:
    53/tcp
    443/tcp
    |-- SSL Versions: TLSv1.2, TLSv1.3
Request (Scan all the services) 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.scan(ips='8.8.8.8', force=False))
Response 
{
    "count": 1,
    "id": "mFN8rs9pcqcmQYOZ",
    "credits_left": 100000
}
Request (Scan specified services) 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
ips = {
    "1.1.1.1": [
        [53, "dns-udp"],
        [443, "https"]
    ],
    "8.8.8.8": [
        [53, "dns-tcp"],
    ],
}
print(api.scan(ips=ips, force=False))
Response 
{
    "count": 2,
    "id": "SDniHKzc4kEWxZPu",
    "credits_left": 100000
}
POST/shodan/scan/internet
Crawl the Internet for a specific port and protocol using Shodan

Use this method to request Shodan to crawl the Internet for a specific port.

Requirements

This method is restricted to security researchers and companies with a Shodan Enterprise Data license. To apply for access to this method as a researcher, please email jmath@shodan.io with information about your project. Access is restricted to prevent abuse.

Request URL 
https://api.shodan.io/shodan/scan/internet?key={YOUR_API_KEY}

Parameters
  • port: [Integer] The port that Shodan should crawl the Internet for.
  • protocol: [String] The name of the protocol that should be used to interrogate the port. See /shodan/protocols for a list of supported protocols.
Examples
Request 
$ curl -X POST "https://api.shodan.io/shodan/scan/internet?key={YOUR_API_KEY}" -d 'port=80' -d 'protocol=http'
Response 
{
    "id": "TcjcsMfPcw4o7O84"
}
Request 
$ shodan scan internet 22 ssh
Response 
Submitting Internet scan to Shodan...Done
The requested port is already indexed by Shodan. A new scan for the port has been launched, please subscribe to the real-time stream for results.
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.scan_internet(port=443, protocol='https'))
Response 
{
    "id": "2kReKZlPxSkCRppx"
}
GET/shodan/scans
Get list of all the created scans

Returns a listing of all the on-demand scans that are currently active on the account.

Request URL 
https://api.shodan.io/shodan/scans?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/scans?key={YOUR_API_KEY}"
Response 
{
    "matches": [
        {
            "status": "PROCESSING",
            "created": "2021-01-26T08:17:43.794000",
            "status_check": "2021-01-26T08:17:43.900000",
            "credits_left": 100000,
            "api_key": "toH56DpDulOnvyxLhOSIxaUgZQeg1gFX",
            "id": "Mo8W7itcWumiy9Ay",
            "size": 1
        },
        {
            "status": "DONE",
            "created": "2021-01-26T08:08:26.296000",
            "status_check": "2021-01-26T08:09:39.636000",
            "credits_left": 100000,
            "api_key": "toH56DpDulOnvyxLhOSIxaUgZQeg1gFX",
            "id": "04GjMnUkQx9HsFhA",
            "size": 1
        },
        ...
    ],
    "total": 19
}
Request 
$ shodan scan list
Response 
# 19 Scans Total - Showing 10 most recent scans:
# Scan ID              Status          Size       Timestamp
vClAi1jq1FjNWmS0       PROCESSING      1          2021-01-26T09:45:21.426000
xHyH8Q8Do7S0KrkW       DONE            2          2021-01-26T08:58:00.418000
...
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.scans(page=1))
Response 
{
    "matches": [
        {
            "status": "PROCESSING",
            "created": "2021-01-26T08:17:43.794000",
            "status_check": "2021-01-26T08:17:43.900000",
            "credits_left": 100000,
            "api_key": "toH56DpDulOnvyxLhOSIxaUgZQeg1gFX",
            "id": "Mo8W7itcWumiy9Ay",
            "size": 1
        },
        {
            "status": "DONE",
            "created": "2021-01-26T08:08:26.296000",
            "status_check": "2021-01-26T08:09:39.636000",
            "credits_left": 100000,
            "api_key": "toH56DpDulOnvyxLhOSIxaUgZQeg1gFX",
            "id": "04GjMnUkQx9HsFhA",
            "size": 1
        },
        ...
    ],
    "total": 19
}
GET/shodan/scan/{id}
Get the status of a scan request
Check the progress of a previously submitted scan request. Possible values for the status are:
  • SUBMITTING
  • QUEUE
  • PROCESSING
  • DONE

Request URL 
https://api.shodan.io/shodan/scan/{id}?key={YOUR_API_KEY}

Parameters
  • id: [String] The unique scan ID that was returned by /shodan/scan.
Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/scan/Mo8W7itcWumiy9Ay?key={YOUR_API_KEY}"
Response 
{
    "count": 1,
    "status": "DONE",
    "id": "Mo8W7itcWumiy9Ay",
    "created": "2021-01-26T08:17:43.794000"
}
Request 
$ shodan scan status Mo8W7itcWumiy9Ay
Response 
DONE
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.scan_status(scan_id='Mo8W7itcWumiy9Ay'))
Response 
{
    "count": 1,
    "status": "DONE",
    "id": "Mo8W7itcWumiy9Ay",
    "created": "2021-01-26T08:17:43.794000"
}

Network Alerts

POST/shodan/alert
Create an alert to monitor a network range

Use this method to create a network alert for a defined IP/ netblock which can be used to subscribe to changes/ events that are discovered within that range.

Request URL 
https://api.shodan.io/shodan/alert?key={YOUR_API_KEY}
Parameters

The alert is created by sending a JSON encoded object that has the structure:

{
    "name": {name},
    "filters": {
        "ip": {ip},
    },
    "expires": {expires},
}
  • name: [String] The name to describe the network alert.
  • filters: [Object] An object specifying the criteria that an alert should trigger. The only supported option at the moment is the "ip" filter.
  • filters.ip: [String] A list of IPs or network ranges defined using CIDR notation.
  • expires (optional): [Integer] Number of seconds that the alert should be active.
Examples
Request 
$ curl -X POST "https://api.shodan.io/shodan/alert?key={YOUR_API_KEY}" -H 'Content-Type: application/json' -d'
    {
        "name": "DNS Alert",
        "filters": {
            "ip": [
                "8.8.8.8",
                "1.1.1.1"
            ]
        },
        "expires": 0
    }
'
Response 
{
    "name": "DNS Alert",
    "created": "2021-01-27T03:44:22.989575",
    "triggers": {},
    "has_triggers": false,
    "expires": 0,
    "expiration": null,
    "filters": {
        "ip": [
            "8.8.8.8",
            "1.1.1.1"
        ]
    },
    "id": "OYPRB8IR9Z35AZPR",
    "size": 2
}
Request 
$ shodan alert create "DNS Alert" 8.8.8.8 1.1.1.1
Response 
Successfully created network alert!
Alert ID: Z05WK08N0568Y53R
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.create_alert(name='DNS Alert', ip=['8.8.8.8', '1.1.1.1'], expires=0))
Response 
{
    "name": "DNS Alert",
    "created": "2021-01-27T03:50:24.277866",
    "triggers": {},
    "has_triggers": False,
    "expires": 0,
    "expiration": None,
    "filters": {
        "ip": [
            "8.8.8.8",
            "1.1.1.1"
        ]
    },
    "id": "67UQ4JM3NGJKROR9",
    "size": 2,
}
GET/shodan/alert/{id}/info
Get the details for a network alert

Returns the information about a specific network alert.

Request URL 
https://api.shodan.io/shodan/alert/{id}/info?key={YOUR_API_KEY}
Parameters
  • id: [String] Alert ID
Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/alert/67UQ4JM3NGJKROR9/info?key={YOUR_API_KEY}"
Response 
{
    "name": "DNS Alert",
    "created": "2021-01-27T03:50:24.277000",
    "triggers": {},
    "has_triggers": false,
    "expires": 0,
    "notify": {},
    "expiration": null,
    "filters": {
        "ip": [
            "8.8.8.8",
            "1.1.1.1"
        ]
    },
    "notifiers": [],
    "id": "67UQ4JM3NGJKROR9",
    "size": 2
}
Request 
$ shodan alert info 67UQ4JM3NGJKROR9
Response 
DNS Alert
Created: 2021-01-27T03:50:24.277000
Notifications: disabled

Network Range(s):
> 8.8.8.8
> 1.1.1.1
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.alerts(aid='67UQ4JM3NGJKROR9', include_expired=True))
Response 
{
    "name": "DNS Alert",
    "created": "2021-01-27T03:50:24.277000",
    "triggers": {},
    "has_triggers": False,
    "expires": 0,
    "notify": {},
    "expiration": None,
    "filters": {
        "ip": [
            "8.8.8.8",
            "1.1.1.1"
        ]
    },
    "notifiers": [],
    "api_key": "toH56DpDulOnvyxLhOSIxaUgZQeg1gFX",
    "id": "67UQ4JM3NGJKROR9",
    "size": 2,
}
DELETE/shodan/alert/{id}
Delete an alert

Remove the specified network alert.

Request URL 
https://api.shodan.io/shodan/alert/{id}?key={YOUR_API_KEY}
Parameters
  • id: [String] Alert ID
Examples
Request 
$ curl -X DELETE "https://api.shodan.io/shodan/alert/67UQ4JM3NGJKROR9?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
$ shodan alert remove 67UQ4JM3NGJKROR9
Response 
Alert deleted
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.delete_alert(aid='67UQ4JM3NGJKROR9'))
Response 
{
    "success": True
}
POST/shodan/alert/{id}
Edit the networks monitored in an alert

Use this method to edit a network alert with a new list of IPs/ networks to keep track of.

Request URL 
https://api.shodan.io/shodan/alert/{id}?key={YOUR_API_KEY}
Parameters

The alert is edited by sending a JSON encoded object that has the structure:

{
    "filters": {
        "ip": {ip},
    },
}
  • filters: [Object] An object specifying the criteria that an alert should trigger. The only supported option at the moment is the "ip" filter.
  • filters.ip: [String] A list of IPs or network ranges defined using CIDR notation.
Examples
Request 
$ curl -X POST "https://api.shodan.io/shodan/alert/67UQ4JM3NGJKROR9?key={YOUR_API_KEY}" -H 'Content-Type: application/json' -d'
    {
        "filters": {
            "ip": [
                "8.8.8.8",
                "1.1.1.1"
            ]
        }
    }
'
Response 
{
    "name": "DNS Alert",
    "created": "2021-01-27T03:44:22.989575",
    "triggers": {},
    "has_triggers": false,
    "expires": 0,
    "expiration": null,
    "filters": {
        "ip": [
            "8.8.8.8",
            "1.1.1.1"
        ]
    },
    "id": "67UQ4JM3NGJKROR9",
    "size": 2
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.edit_alert('67UQ4JM3NGJKROR9', ['8.8.8.8', '1.1.1.1']))
Response 
{
    "name": "DNS Alert",
    "created": "2021-01-27T03:50:24.277866",
    "triggers": {},
    "has_triggers": False,
    "expires": 0,
    "expiration": None,
    "filters": {
        "ip": [
            "8.8.8.8",
            "1.1.1.1"
        ]
    },
    "id": "67UQ4JM3NGJKROR9",
    "size": 2,
}
GET/shodan/alert/info
Get a list of all the created alerts

Returns a listing of all the network alerts that are currently active on the account.

Request URL 
https://api.shodan.io/shodan/alert/info?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/alert/info?key={YOUR_API_KEY}"
Response 
[
    {
        "name": "DNS Alert",
        "created": "2021-01-27T03:44:22.989000",
        "triggers": {},
        "has_triggers": false,
        "expires": 0,
        "notify": {},
        "expiration": null,
        "filters": {
            "ip": [
                "8.8.8.8",
                "1.1.1.1"
            ]
        },
        "notifiers": [],
        "id": "OYPRB8IR9Z35AZPR",
        "size": 2
    },
    {
        "name": "Google DNS Alert",
        "created": "2021-01-27T03:42:50.908000",
        "triggers": {},
        "has_triggers": false,
        "expires": 0,
        "notify": {},
        "expiration": null,
        "filters": {
            "ip": [
                "8.8.8.8"
            ]
        },
        "notifiers": [],
        "id": "RIO8WNQZMI4ZQXW6",
        "size": 1
    },
    ...
]
Request 
$ shodan alert list
Response 
# Alert ID       Name                  IP/ Network
OYPRB8IR9Z35AZPR DNS Alert             8.8.8.8, 1.1.1.1
RIO8WNQZMI4ZQXW6 Google DNS Alert      8.8.8.8
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.alerts(include_expired=True))
Response 
[
    {
        "name": "DNS Alert",
        "created": "2021-01-27T03:44:22.989000",
        "triggers": {},
        "has_triggers": False,
        "expires": 0,
        "notify": {},
        "expiration": None,
        "filters": {
            "ip": [
                "8.8.8.8",
                "1.1.1.1"
            ]
        },
        "notifiers": [],
        "api_key": "toH56DpDulOnvyxLhOSIxaUgZQeg1gFX",
        "id": "OYPRB8IR9Z35AZPR",
        "size": 2,
    },
    {
        "name": "Google DNS Alert",
        "created": "2021-01-27T03:42:50.908000",
        "triggers": {},
        "has_triggers": False,
        "expires": 0,
        "notify": {},
        "expiration": None,
        "filters": {
            "ip": [
                "8.8.8.8"
            ]
        },
        "notifiers": [],
        "api_key": "toH56DpDulOnvyxLhOSIxaUgZQeg1gFX",
        "id": "RIO8WNQZMI4ZQXW6",
        "size": 1,
    },
    ...
]
GET/shodan/alert/triggers
Get a list of available triggers

Returns a list of all the triggers that can be enabled on network alerts.

Request URL 
https://api.shodan.io/shodan/alert/triggers?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/alert/triggers?key={YOUR_API_KEY}"
Response 
[
    {
        "name": "any",
        "rule": "*",
        "description": "Match any service that is discovered"
    },
    {
        "name": "industrial_control_system",
        "rule": "tag:ics",
        "description": "Services associated with industrial control systems"
    },
    {
        "name": "malware",
        "rule": "tag:compromised,malware",
        "description": "Compromised or malware-related services"
    },
    {
        "name": "uncommon",
        "rule": "-port:22,80,443,7547",
        "description": "Services that generally shouldn't be publicly available"
    },
    ...
]
Request 
$ shodan alert triggers
Response 
The following triggers can be enabled on alerts:

Name         any
Description  Match any service that is discovered
Rule         *

Name         industrial_control_system
Description  Services associated with industrial control systems
Rule         tag:ics

Name         internet_scanner
Description  Device has been seen scanning the Internet and exposes a service
Rule         tags:scanner

...
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.alert_triggers())
Response 
[
    {
        "name": "any",
        "rule": "*",
        "description": "Match any service that is discovered"
    },
    {
        "name": "industrial_control_system",
        "rule": "tag:ics",
        "description": "Services associated with industrial control systems",
    },
    ...
]
PUT/shodan/alert/{id}/trigger/{trigger}
Enable a trigger

Get notifications when the specified trigger is met.

Request URL 
https://api.shodan.io/shodan/alert/{id}/trigger/{trigger}?key={YOUR_API_KEY}
Parameters
  • id: [String] Alert ID
  • trigger: [String] Comma-separated list of trigger names
Examples
Request 
$ curl -X PUT "https://api.shodan.io/shodan/alert/OYPRB8IR9Z35AZPR/trigger/new_service,vulnerable?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
$ shodan alert enable OYPRB8IR9Z35AZPR new_service,vulnerable
Response 
Successfully enabled the trigger: new_service,vulnerable
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.enable_alert_trigger(aid='OYPRB8IR9Z35AZPR', trigger='new_service,vulnerable'))
Response 
{
    "success": True
}
DELETE/shodan/alert/{id}/trigger/{trigger}
Disable a trigger

Stop getting notifications for the specified trigger.

Request URL 
https://api.shodan.io/shodan/alert/{id}/trigger/{trigger}?key={YOUR_API_KEY}
Parameters
  • id: [String] Alert ID
  • trigger: [String] Comma-separated list of trigger names
Examples
Request 
$ curl -X DELETE "https://api.shodan.io/shodan/alert/OYPRB8IR9Z35AZPR/trigger/new_service,vulnerable?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
$ shodan alert disable OYPRB8IR9Z35AZPR new_service,vulnerable
Response 
Successfully disabled the trigger: new_service,vulnerable
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.disable_alert_trigger(aid='OYPRB8IR9Z35AZPR', trigger='new_service,vulnerable'))
Response 
{
    "success": True
}
PUT/shodan/alert/{id}/trigger/{trigger}/ignore/{service}
Add to Whitelist

Ignore the specified service when it is matched for the trigger.

Request URL 
https://api.shodan.io/shodan/alert/{id}/trigger/{trigger}/ignore/{service}?key={YOUR_API_KEY}
Parameters
  • id: [String] Alert ID
  • trigger: [String] Trigger name
  • service: [String] Service specified in the format "ip:port" (ex. "1.1.1.1:80"
Examples
Request 
$ curl -X PUT "https://api.shodan.io/shodan/alert/OYPRB8IR9Z35AZPR/trigger/new_service/ignore/1.1.1.1:53?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.ignore_alert_trigger_notification(aid='OYPRB8IR9Z35AZPR', trigger='new_service', ip='1.1.1.1', port=53))
Response 
{
    "success": True
}
DELETE/shodan/alert/{id}/trigger/{trigger}/ignore/{service}
Remove from Whitelist

Start getting notifications again for the specified trigger.

Request URL 
https://api.shodan.io/shodan/alert/{id}/trigger/{trigger}/ignore/{service}?key={YOUR_API_KEY}
Parameters
  • id: [String] Alert ID
  • trigger: [String] Trigger name
  • service: [String] Service specified in the format "ip:port" (ex. "1.1.1.1:80"
Examples
Request 
$ curl -X DELETE "https://api.shodan.io/shodan/alert/OYPRB8IR9Z35AZPR/trigger/new_service/ignore/1.1.1.1:53?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.unignore_alert_trigger_notification(aid='OYPRB8IR9Z35AZPR', trigger='new_service', ip='1.1.1.1', port=53))
Response 
{
    "success": True
}
PUT/shodan/alert/{id}/notifier/{notifier_id}
Add the notifier to the alert

Add the specified notifier to the network alert. Notifications are only sent if triggers have also been enabled. For each created user, there is a default notifier which will sent via email.

Request URL 
https://api.shodan.io/shodan/alert/{id}/notifier/{notifier_id}?key={YOUR_API_KEY}
Parameters
  • id: [String] Alert ID
  • notifier_id: [String] Notifier ID
Examples
Request 
$ curl -X PUT "https://api.shodan.io/shodan/alert/OYPRB8IR9Z35AZPR/notifier/default?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.add_alert_notifier(aid='OYPRB8IR9Z35AZPR', nid='default'))
Response 
{
    "success": True
}
DELETE/shodan/alert/{id}/notifier/{notifier_id}
Remove the notifier from the alert

Remove the notification service from the alert. Notifications are only sent if triggers have also been enabled.

Request URL 
https://api.shodan.io/shodan/alert/{id}/notifier/{notifier_id}?key={YOUR_API_KEY}
Parameters
  • id: [String] Alert ID
  • notifier_id: [String] Notifier ID
Examples
Request 
$ curl -X DELETE "https://api.shodan.io/shodan/alert/OYPRB8IR9Z35AZPR/notifier/default?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.remove_alert_notifier(aid='OYPRB8IR9Z35AZPR', nid='default'))
Response 
{
    "success": True
}

Notifiers

GET/notifier
List all user-created notifiers

Get a list of all the notifiers that the user has created.

Request URL 
https://api.shodan.io/notifier?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/notifier?key={YOUR_API_KEY}"
Response 
{
    "matches": [
        {
            "description": null,
            "args": {
                "to": "jmath@shodan.io"
            },
            "provider": "email",
            "id": "default"
        },
        ...
    ],
    "total": 2
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.notifier.list_notifiers())
Response 
{
    "matches": [
        {
            "description": null,
            "args": {
                "to": "jmath@shodan.io"
            },
            "provider": "email",
            "id": "default"
        },
        ...
    ],
    "total": 2
}
GET/notifier/provider
List of available notification providers

Get a list of all the notification providers that are available and the parameters to submit when creating them.

Request URL 
https://api.shodan.io/notifier/provider?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/notifier/provider?key={YOUR_API_KEY}"
Response 
{
    "pagerduty": {
        "required": [
            "routing_key"
        ]
    },
    "slack": {
        "required": [
            "webhook_url"
        ]
    },
    "telegram": {
        "required": [
            "chat_id",
            "token"
        ]
    },
    "webhook": {
        "required": [
            "url"
        ]
    },
    "phone": {
        "required": [
            "to"
        ]
    },
    "email": {
        "required": [
            "to"
        ]
    },
    "gitter": {
        "required": [
            "room_id",
            "token"
        ]
    }
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.notifier.list_providers())
Response 
{
    "pagerduty": {
        "required": [
            "routing_key"
        ]
    },
    "slack": {
        "required": [
            "webhook_url"
        ]
    },
    "telegram": {
        "required": [
            "chat_id",
            "token"
        ]
    },
    "webhook": {
        "required": [
            "url"
        ]
    },
    "phone": {
        "required": [
            "to"
        ]
    },
    "email": {
        "required": [
            "to"
        ]
    },
    "gitter": {
        "required": [
            "room_id",
            "token"
        ]
    }
}
POST/notifier
Create a new notification service for the user

Use this method to create a new notification service endpoint that Shodan services can send notifications through.

Request URL 
https://api.shodan.io/notifier?key={YOUR_API_KEY}
Parameters
The parameters depend on the type of notification service that is being created. To get a list of parameters for a provider us the /notifier/provider endpoint. The following parameters always need to be provided:
  • provider: [String] Provider name as returned by /notifier/provider
  • description: [String] Description of the notifier
  • **args: [String] Arguments required by the provider
Examples
Request 
$ curl -X POST "https://api.shodan.io/notifier?key={YOUR_API_KEY}" -d 'provider=email' -d 'description=Email notifier' -d 'to=jmath@shodan.io'
Response 
{
    "id": "1VxiaJb93Gn8TUnM",
    "success": true
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.notifier.create(provider='email', args={'to': 'jmath@shodan.io'}, description='Email notifier'))
Response 
{
    "id": "1VxiaJb93Gn8TUnM",
    "success": True
}
DELETE/notifier/{id}
Delete a notification service

Remove the notification service created for the user.

Request URL 
https://api.shodan.io/notifier/{id}?key={YOUR_API_KEY}
Parameters
  • id: [String] Notifier ID
Examples
Request 
$ curl -X DELETE "https://api.shodan.io/notifier/1VxiaJb93Gn8TUnM?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.notifier.remove(nid='1VxiaJb93Gn8TUnM'))
Response 
{
    "success": True
}
GET/notifier/{id}
Get information about a notifier

Use this method to create a new notification service endpoint that Shodan services can send notifications through.

Request URL 
https://api.shodan.io/notifier/{id}?key={YOUR_API_KEY}
Parameters
  • id: [String] Notifier ID
Examples
Request 
$ curl -X GET "https://api.shodan.io/notifier/1VxiaJb93Gn8TUnM?key={YOUR_API_KEY}"
Response 
{
    "description": "Email notifier",
    "args": {
        "to": "jmath@shodan.io"
    },
    "provider": "email",
    "id": "1VxiaJb93Gn8TUnM"
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.notifier.get(nid='1VxiaJb93Gn8TUnM'))
Response 
{
    "description": "Email notifier",
    "args": {
        "to": "jmath@shodan.io"
    },
    "provider": "email",
    "id": "1VxiaJb93Gn8TUnM"
}
PUT/notifier/{id}
Edit a notifier

Use this method to update the parameters of a notifier.

Request URL 
https://api.shodan.io/notifier/{id}?key={YOUR_API_KEY}
Parameters

The parameters depend on the type of notification service that is being created. To get a list of parameters for a provider us the /notifier/provider endpoint.

  • id: [String] Notifier ID
  • **args: [String] Arguments required by the provider
Examples
Request 
$ curl -X PUT "https://api.shodan.io/notifier/1VxiaJb93Gn8TUnM?key={YOUR_API_KEY}" -d 'to=jmath@gmail.com'
Response 
{
    "id": "1VxiaJb93Gn8TUnM",
    "success": true
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.notifier.edit(nid='1VxiaJb93Gn8TUnM', args={'to': 'jmath@gmail.com'}))
Response 
{
    "id": "1VxiaJb93Gn8TUnM",
    "success": true
}

Directory Methods

GET/shodan/query
List the saved search queries

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

Request URL 
https://api.shodan.io/shodan/query?key={YOUR_API_KEY}
Parameters
  • page (optional): [Integer] Page number to iterate over results; each page contains 10 items
  • sort (optional): [String] Sort the list based on a property. Possible values are: votes, timestamp
  • order (optional): [String] Whether to sort the list in ascending or descending order. Possible values are: asc, desc
Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/query?key={YOUR_API_KEY}"
Response 
{
    "matches": [
        {
            "votes": 1,
            "description": "Danieverton",
            "tags": [
                ""
            ],
            "timestamp": "2021-01-26T19:41:50.961000",
            "title": "ip camera",
            "query": "ip camera BR"
        },
        {
            "votes": 3,
            "description": "This is Moxa Nport Devices ICS system with Authentication disabled Author: A1C3VENOM",
            "tags": [
                "ics",
                "iot",
                "moxa"
            ],
            "timestamp": "2021-01-24T07:44:08.889000",
            "title": "Moxa Nport Devices with Authentication disabled",
            "query": "\"Moxa Nport Device\" Status: Authentication disabled port:\"4800\""
        },
        ...
    ],
    "total": 6746
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.queries(page=1, sort='timestamp', order='desc'))
Response 
{
    "matches": [
        {
            "votes": 1,
            "description": "Danieverton",
            "tags": [
                ""
            ],
            "timestamp": "2021-01-26T19:41:50.961000",
            "title": "ip camera",
            "query": "ip camera BR",
        },
        {
            "votes": 3,
            "description": "This is Moxa Nport Devices ICS system with Authentication disabled Author: A1C3VENOM",
            "tags": [
                "ics",
                "iot",
                "moxa"
            ],
            "timestamp": "2021-01-24T07:44:08.889000",
            "title": "Moxa Nport Devices with Authentication disabled",
            "query": '"Moxa Nport Device" Status: Authentication disabled port: "4800"',
        },
        ...
    ],
    "total": 6746,
}
GET/shodan/query/search
GET/shodan/query/tags
List the most popular tags

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

Request URL 
https://api.shodan.io/shodan/query/tags?key={YOUR_API_KEY}
Parameters
  • size (optional): [Integer] The number of tags to return (default: 10).
Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/query/tags?key={YOUR_API_KEY}"
Response 
{
    "matches": [
        {
            "count": 209,
            "value": "webcam"
        },
        {
            "count": 172,
            "value": "cam"
        },
        {
            "count": 159,
            "value": "camera"
        },
        ...
    ],
    "total": 7580
}
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.queries_tags(size=10))
Response 
{
    "matches": [
        {
            "count": 209,
            "value": "webcam"
        },
        {
            "count": 172,
            "value": "cam"
        },
        {
            "count": 159,
            "value": "camera"
        },
        ...
    ],
    "total": 7580
}

Bulk Data  Enterprise

GET/shodan/data
Get a list of available datasets

Use this method to see a list of the datasets that are available for download.

Request URL 
https://api.shodan.io/shodan/data?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/data?key={YOUR_API_KEY}"
Response 
[
    {
        "scope": "monthly",
        "name": "country",
        "description": "Data broken down by country of the device"
    },
    {
        "scope": "daily",
        "name": "ships",
        "description": "AIS data from public receivers"
    },
    {
        "scope": "daily",
        "name": "ping",
        "description": "Ping sweeps of the entire IPv4 as well as statistical breakdown of devices by country"
    },
    {
        "scope": "monthly",
        "name": "dnsdb",
        "description": "DNS data for active domains on the Internet"
    },
    {
        "scope": "daily",
        "name": "raw-daily",
        "description": "Data files containing all the information collected during a day"
    }
]
Request 
$ shodan data list
Response 
country        Data broken down by country of the device
ships          AIS data from public receivers
ping           Ping sweeps of the entire IPv4 as well as statistical breakdown of devices by country
dnsdb          DNS data for active domains on the Internet
raw-daily      Data files containing all the information collected during a day
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.data.list_datasets())
Response 
[
    {
        "scope": "monthly",
        "name": "country",
        "description": "Data broken down by country of the device"
    },
    {
        "scope": "daily",
        "name": "ships",
        "description": "AIS data from public receivers"
    },
    {
        "scope": "daily",
        "name": "ping",
        "description": "Ping sweeps of the entire IPv4 as well as statistical breakdown of devices by country"
    },
    {
        "scope": "monthly",
        "name": "dnsdb",
        "description": "DNS data for active domains on the Internet"
    },
    {
        "scope": "daily",
        "name": "raw-daily",
        "description": "Data files containing all the information collected during a day"
    }
]
GET/shodan/data/{dataset}
List the files for a dataset

Get a list of files that are available for download from the provided dataset.

Request URL 
https://api.shodan.io/shodan/data/{dataset}?key={YOUR_API_KEY}
Parameters
  • dataset: [String] Name of the dataset
Examples
Request 
$ curl -X GET "https://api.shodan.io/shodan/data/raw-daily?key={YOUR_API_KEY}"
Response 
[
    {
        "url": "https://...",
        "timestamp": 1611711401000,
        "sha1": "5a91f49c90da5ab8856c83c84846941115c55441",
        "name": "2021-01-26.json.gz",
        "size": 104650655998
    },
    {
        "url": "https://...",
        "timestamp": 1611655444000,
        "sha1": "ea29acc25fc154ac64dde0ab294824ae7f1f64c9",
        "name": "2021-01-25.json.gz",
        "size": 152517565458
    },
    {
        "url": "https://...",
        "timestamp": 1611540775000,
        "sha1": "aed18f2a952df7731fec447d81ead8a96907000d",
        "name": "2021-01-24.json.gz",
        "size": 161275556509
    },
    ...
]
Request 
$ shodan data list --dataset raw-daily
Response 
2021-01-26.json.gz  97.5 GB   5a91f49c90da5ab8856c83c84846941115c55441  https://...
2021-01-25.json.gz  142.0 GB  ea29acc25fc154ac64dde0ab294824ae7f1f64c9  https://...
2021-01-24.json.gz  150.2 GB  aed18f2a952df7731fec447d81ead8a96907000d  https://...
...
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.data.list_files(dataset='raw-daily'))
Response 
[
    {
        "url": "https://...",
        "timestamp": 1611711401000,
        "sha1": "5a91f49c90da5ab8856c83c84846941115c55441",
        "name": "2021-01-26.json.gz",
        "size": 104650655998
    },
    {
        "url": "https://...",
        "timestamp": 1611655444000,
        "sha1": "ea29acc25fc154ac64dde0ab294824ae7f1f64c9",
        "name": "2021-01-25.json.gz",
        "size": 152517565458
    },
    {
        "url": "https://...",
        "timestamp": 1611540775000,
        "sha1": "aed18f2a952df7731fec447d81ead8a96907000d",
        "name": "2021-01-24.json.gz",
        "size": 161275556509
    },
    ...
]

Manage Organization Enterprise

GET/org
General Information

Get information about your organization such as the list of its members, upgrades, authorized domains and more.

Request URL 
https://api.shodan.io/org?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/org?key={YOUR_API_KEY}"
Response 
{
    "name": "Shodan Organization",
    "created": "2020-09-30T15:41:48.073000",
    "admins": [
        {
            "username": "admin",
            "email": "admin@shodan.io"
        }
    ],
    "members": [
        {
            "username": "member",
            "email": "member@shodan.io"
        }
    ],
    "upgrade_type": "stream-100",
    "domains": [
        "shodan.io"
    ],
    "logo": false,
    "id": "p3cEAmoDapAPeP7w"
}
Request 
$ shodan org info
Response 
Shodan Organization
Access Level: Enterprise
Authorized Domains: shodan.io

Administrators:
> admin                	admin@shodan.io

Members:
> member               	member@shodan.io
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.org.info())
Response 
{
    "name": "Shodan Organization",
    "created": "2020-09-30T15:41:48.073000",
    "admins": [
        {
            "username": "admin",
            "email": "admin@shodan.io"
        }
    ],
    "members": [
        {
            "username": "member",
            "email": "member@shodan.io"
        }
    ],
    "upgrade_type": "stream-100",
    "domains": [
        "shodan.io"
    ],
    "logo": false,
    "id": "p3cEAmoDapAPeP7w"
}
PUT/org/member/{user}
Add a new member

Add a Shodan user to the organization and upgrade them.

Request URL 
https://api.shodan.io/org/member/{user}?key={YOUR_API_KEY}
Parameters
  • user: [String] Username or email of the Shodan user
  • notify (optional): [Boolean] Whether or not to send an email notification
Examples
Request 
$ curl -X PUT "https://api.shodan.io/org/member/new-member@shodan.io?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
$ shodan org add new-member@shodan.io
Response 
Successfully added the new member
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.org.add_member(user='new-member@shodan.io', notify=True))
Response 
True
DELETE/org/member/{user}
Remove a member

Remove and downgrade the provided member from the organization.

Request URL 
https://api.shodan.io/org/member/{user}?key={YOUR_API_KEY}
Parameters
  • user: [String] Username or email of the Shodan user
Examples
Request 
$ curl -X DELETE "https://api.shodan.io/org/member/new-member@shodan.io?key={YOUR_API_KEY}"
Response 
{
    "success": true
}
Request 
$ shodan org remove new-member@shodan.io
Response 
Successfully removed the new member
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.org.remove_member(user='new-member@shodan.io'))
Response 
True

Account Methods

GET/account/profile
Account Profile

Returns information about the Shodan account linked to this API key.

Request URL 
https://api.shodan.io/account/profile?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/account/profile?key={YOUR_API_KEY}"
Response 
{
    "member": true,
    "credits": 0,
    "display_name": null,
    "created": "2020-06-15T10:44:43.148000"
}

DNSMethods

GET/dns/domain/{domain}
Domain Information

Get all the subdomains and other DNS entries for the given domain. Uses 1 query credit per lookup.

Request URL 
https://api.shodan.io/dns/domain/{domain}?key={YOUR_API_KEY}
Parameters
  • domain: [String] Domain name to lookup; example "cnn.com"
  • history (optional): [Boolean] True if historical DNS data should be included in the results (default: False)
  • type (optional): [String] DNS type, possible values are: A, AAAA, CNAME, NS, SOA, MX, TXT
  • page (optional): [Integer] The page number to page through results 100 at a time (default: 1)
Examples
Request 
$ curl -X GET "https://api.shodan.io/dns/domain/google.com?key={YOUR_API_KEY}"
Response 
{
    "domain": "google.com",
    "tags": [
        "ipv6"
    ],
    "data": [
        {
            "subdomain": "",
            "type": "MX",
            "value": "aspmx.l.google.com",
            "last_seen": "2021-01-19T22:23:15.978799+00:00"
        },
        {
            "subdomain": "*.auth.corp",
            "type": "CNAME",
            "value": "uberproxy.l.google.com",
            "last_seen": "2021-01-26T13:04:34.018114+00:00"
        },
        {
            "subdomain": "*.cloud.sandbox",
            "type": "A",
            "value": "74.125.142.81",
            "last_seen": "2021-01-15T12:57:18.133727+00:00"
        },
        ...
    ],
    "subdomains": [
        "*.auth.corp",
        "*.cloud.sandbox",
        "*.composer-staging.cloud",
        ...
    ],
    "more": true
}
Request 
$ shodan domain google.com
Response 
GOOGLE.COM

                            MX     aspmx.l.google.com
*.auth.corp              CNAME  uberproxy.l.google.com
*.cloud.sandbox          A      74.125.142.81
*.composer-staging.cloud  CNAME  www3.l.google.com
...
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.dns.domain_info(domain='google.com', history=False, type=None, page=1))
Response 
{
    "domain": "google.com",
    "tags": [
        "ipv6"
    ],
    "data": [
        {
            "subdomain": "",
            "type": "MX",
            "value": "aspmx.l.google.com",
            "last_seen": "2021-01-19T22:23:15.978799+00:00"
        },
        {
            "subdomain": "*.auth.corp",
            "type": "CNAME",
            "value": "uberproxy.l.google.com",
            "last_seen": "2021-01-26T13:04:34.018114+00:00"
        },
        {
            "subdomain": "*.cloud.sandbox",
            "type": "A",
            "value": "74.125.142.81",
            "last_seen": "2021-01-15T12:57:18.133727+00:00"
        },
        ...
    ],
    "subdomains": [
        "*.auth.corp",
        "*.cloud.sandbox",
        "*.composer-staging.cloud",
        ...
    ],
    "more": true
}
GET/dns/resolve
DNS Lookup

Look up the IP address for the provided list of hostnames.

Request URL 
https://api.shodan.io/dns/resolve?hostnames={hostnames}&key={YOUR_API_KEY}
Parameters
  • hostnames: [String] Comma-separated list of hostnames; example "google.com,bing.com"
Examples
Request 
$ curl -X GET "https://api.shodan.io/dns/resolve?hostnames=google.com,facebook.com&key={YOUR_API_KEY}"
Response 
{
    "google.com": "172.217.6.46",
    "facebook.com": "157.240.22.35"
}
GET/dns/reverse
Reverse DNS Lookup

Look up the hostnames that have been defined for the given list of IP addresses.

Request URL 
https://api.shodan.io/dns/reverse?ips={ips}&key={YOUR_API_KEY}
Parameters
  • ips: [String] Comma-separated list of IP addresses; example "74.125.227.230,204.79.197.200"
Examples
Request 
$ curl -X GET "https://api.shodan.io/dns/reverse?ips=8.8.8.8,1.1.1.1&key={YOUR_API_KEY}"
Response 
{
    "8.8.8.8": [
        "dns.google"
    ],
    "1.1.1.1": [
        "one.one.one.one"
    ]
}

Utility Methods

GET/tools/httpheaders
HTTP Headers

Shows the HTTP headers that your client sends when connecting to a webserver.

Request URL 
https://api.shodan.io/tools/httpheaders?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/tools/httpheaders?key={YOUR_API_KEY}"
Response 
{
    "Content-Length": "",
    "Cf-Visitor": "{\"scheme\":\"https\"}",
    "Accept-Encoding": "gzip",
    "X-Forwarded-For": "113.161.57.41",
    "Host": "api.shodan.io",
    "Cf-Request-Id": "07e880ae180000d1cfb309a000000001",
    "User-Agent": "curl/7.64.1",
    "Connection": "Keep-Alive",
    "X-Forwarded-Proto": "https",
    "Accept": "*/*",
    "Cdn-Loop": "cloudflare",
    "Cf-Connecting-Ip": "113.161.57.41",
    "Cf-Ray": "61876a29cdf8d1cf-DFW",
    "Content-Type": ""
}
GET/tools/myip
My IP Address

Get your current IP address as seen from the Internet.

Request URL 
https://api.shodan.io/tools/myip?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/tools/myip?key={YOUR_API_KEY}"
Response 
"113.161.57.41"

API Status Methods

GET/api-info
API Plan Information

Returns information about the API plan belonging to the given API key.

Request URL 
https://api.shodan.io/api-info?key={YOUR_API_KEY}

Examples
Request 
$ curl -X GET "https://api.shodan.io/api-info?key={YOUR_API_KEY}"
Response 
{
    "scan_credits": 100000,
    "usage_limits": {
        "scan_credits": -1,
        "query_credits": -1,
        "monitored_ips": -1
    },
    "plan": "stream-100",
    "https": false,
    "unlocked": true,
    "query_credits": 100000,
    "monitored_ips": 19,
    "unlocked_left": 100000,
    "telnet": false
}
Request 
$ shodan info
Response 
Query credits available: 100000
Scan credits available: 100000
Request 
from shodan import Shodan

api = Shodan('{YOUR_API_KEY}')
print(api.info())
Response 
{
    "scan_credits": 100000,
    "usage_limits": {
        "scan_credits": -1,
        "query_credits": -1,
        "monitored_ips": -1
    },
    "plan": "stream-100",
    "https": False,
    "unlocked": True,
    "query_credits": 100000,
    "monitored_ips": 19,
    "unlocked_left": 100000,
    "telnet": False,
}

Error Handling

A non-200 status code in the response indicates an error occurred. Along with a non-200 error code, the error response will also include a message containing the reason for the failure.

Sample Response 
{
    "error": "Invalid IP"
}
Next: Streaming API Documentation



Products
Pricing
Contact Us

Shodan ® - All rights reserved