Getting Started

Backscatter.io was built as an API-first service, though not tailored to developers. Our goal with our API is to enable anyone––even those with limited exposure to code––to be able to successfully query our services and get back data. All API endpoints are hosted on `api.backscatter.io` and return a JSON response.

When accessing Backscatter.io endpoints, it's preferred to use the official libraries over calling the API directly. Libraries are always in sync with the latest version of the API and offer additional helper functionality like command-line utilities, data processing and more. Check out the clients section for more details on which libraries are available.

Service Level

We offer free accounts!

Not looking to commit to a paid plan? No problem. Backscatter offers a free plan with plenty of queries.

Your access to Backscatter is dictated by your plan. Plans describe how often you can query the API, what data you are allowed to see and what timeframe your query is executed against.

Authorization

Requests to our services are authenticated using an API key. Once you have verified your email, you can see your API key within your account settings. To make a successful request, you must include an HTTP Header of `X-API-KEY` with the value of your API key. Treat this key like a password and do not share it with anyone else or publish it online.

Test Your Key

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/hello
                                        
Successful Response

{
  "message": "bonjour",
  "success": true
}
                                        

Endpoints

Endpoints are grouped into sections based on their functionality.

Observations

Backscatter has several sensors deployed to the Internet that listen for probing activity. When probes are sent to these sensors, they are logged to include the source and metadata associated with the request. This information forms the basis for observations.

Sample Response

This is a complete response and may not reflect what you see if your service level differs

IP Address

Endpoint: /v0/observations/ip

Returns all events where the IP address supplied has been observed as a source for probing.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_observations(query='8.8.8.8', query_type='ip')
print(data)
                                                    

backscatter observations --query 8.8.8.8
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/observations/ip"
full_url = url + endpoint
params = {'query': '8.8.8.8'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/observations/ip?query=8.8.8.8
                                                    

Network

Endpoint: /v0/observations/network

Returns all events where the network block supplied has been observed as a source for probing.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_observations(query='74.96.0.0/16', query_type='network')
print(data)
                                                    

backscatter observations --query 74.96.0.0/16
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/observations/network"
full_url = url + endpoint
params = {'query': '74.96.0.0/16'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/observations/network?query=74.96.0.0/16
                                                    

ASN

Endpoint: /v0/observations/asn

Returns all events where the ASN supplied has been observed as a source for probing.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_observations(query='701', query_type='asn')
print(data)
                                                    

backscatter observations --query 701 --type asn
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/observations/asn"
full_url = url + endpoint
params = {'query': '701'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/observations/asn?query=701
                                                    

Port

Endpoint: /v0/observations/port

Returns all events where the port supplied has been observed as a destination for probing.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_observations(query='6666', query_type='port')
print(data)

                                                    

backscatter observations --query 6666 --type port
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/observations/port"
full_url = url + endpoint
params = {'query': '6666'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/observations/port?query=6666
                                                    

Country

Endpoint: /v0/observations/location

Returns all events where the country supplied has been observed as a source for probing.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_observations(query='US', query_type='country')
print(data)
                                                    

backscatter observations --query US --type country
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/observations/country"
full_url = url + endpoint
params = {'query': 'US'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/observations/country?query=US
                                                    

IP Address

Endpoint: /v0/trends/popular/ip

Returns a listing of top n IP addresses observed over the query scope.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_trends(trend_type='ip')
print(data)
                                                    

backscatter trends --type ip
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/trends/popular/ip"
full_url = url + endpoint
params = {'scope': '1d'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/trends/popular/ip
                                                    

Network

Endpoint: /v0/trends/popular/network

Returns a listing of top n networks observed over the query scope.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_trends(trend_type='network')
print(data)
                                                    

backscatter trends --type network
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/trends/popular/network"
full_url = url + endpoint
params = {'scope': '1d'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/trends/popular/network
                                                    

ASN

Endpoint: /v0/trends/popular/network

Returns a listing of top n ASN observed over the query scope.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_trends(trend_type='asn')
print(data)
                                                    

backscatter trends --type asn
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/trends/popular/asn"
full_url = url + endpoint
params = {'scope': '1d'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/trends/popular/asn
                                                    

Port

Endpoint: /v0/trends/popular/port

Returns a listing of top n ports observed over the query scope.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_trends(trend_type='port')
print(data)
                                                    

backscatter trends --type port
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/trends/popular/port"
full_url = url + endpoint
params = {'scope': '1d'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/trends/popular/port
                                                    

Country

Endpoint: /v0/trends/popular/country

Returns a listing of top n countries observed over the query scope.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.get_trends(trend_type='country')
print(data)
                                                    

backscatter trends --type country
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/trends/popular/country"
full_url = url + endpoint
params = {'scope': '1d'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/trends/popular/country
                                                    

Enrichment

Enrichment data serves as further context for various data types including IP addresses, network blocks and autonomous systems. The endpoint is published separately in order to provide convenience and limit the size of responses.

IP Address

Endpoint: /v0/enrichment/ip

Returns enrichment data for an IP address to include AS, network and geolocation data.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.enrich(query='74.96.192.82')
print(data)
                                                    

backscatter enrich --query 74.96.192.82
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/enrichment/ip"
full_url = url + endpoint
params = {'query': '74.96.192.82'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/enrichment/ip?query=74.96.192.82
                                                    

Sample Response

Network

Endpoint: /v0/enrichment/network

Returns enrichment data for a network to include valid addresses and block size.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.enrich(query='74.96.0.0/32')
print(data)
                                                    

backscatter enrich --query 74.96.0.0/32
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/enrichment/network"
full_url = url + endpoint
params = {'query': '74.96.0.0/32'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/enrichment/network?query=74.96.0.0/32
                                                    

Sample Response

Autonomous System

Endpoint: /v0/enrichment/asn

Returns enrichment data for an ASN to include prefixes and AS name.


from backscatter import Backscatter

bs = Backscatter(api_key='YOUR-KEY')
data = bs.enrich(query='701', query_type='asn')
print(data)
                                                    

backscatter enrich --query 701 --type asn
                                                    

import json
import requests

url = "https://api.backscatter.io"
endpoint = "/v0/enrichment/asn"
full_url = url + endpoint
params = {'query': '701'}
headers = {'X-API-KEY': 'YOUR-KEY'}
response = requests.get(full_url, params=params, headers=headers)
loaded = json.loads(response.content)
data = json.dumps(loaded, indent=4)
print(data)
                                                    

$ curl -XGET \
    --header "X-API-KEY:YOUR-KEY" \
    https://api.backscatter.io/v0/enrichment/asn?query=701
                                                    

Sample Response

Code Clients

We strive to make interacting with our platform as easy as possible. Our primary code client supports the Python programming language. If you have suggestions on other clients you'd like to see, send us a message at info@backscatter.io.

Python

The Python code client is opensource and available on Github or through Pypi. We suggest installing through Pypi as it will handle the details behind installation and future upgrades. Once installed, you can import the Backscatter interface directly in your code or use the command-line utility that comes with the client.

Get the Client


pip install backscatter
                                        

For more details and examples, see the documentation on this page.