Censys REST API


The Censys REST API provides programmatic access to the same data accessible through web interface. API access is governed by our Terms of Service and all scripted access should use this API. We list our API endpoints below.

Connecting


All API endpoints are hosted at https://www.censys.io/api/v1/ and require authenticating with HTTP basic auth using the API ID and secret that are shown under My Account. This page also lists the rate limits that apply to your account.

API Endpoints


We provide the following API endpoints:

search
The search endpoint allows searches against the IPv4, Alexa Top Million, and Certificates indexes using the same search syntax as the main site. The endpoint returns a paginated result of the most recent information we know for the set of user selected fields. More information about the returned hosts, websites, and certificates can be fetched using the /view endpoint.
view
The view endpoint fetches the structured data we have about a specific host, website, or certificate once you know the host's IP address, website's domain, or certificate's SHA-256 fingerprint.
report
The report endpoint allows you to determine the aggregate breakdown of a value for the results a query, similar to the "Build Report" functionality available in the primary search interface. For example, if you wanted to determine the breakdown of cipher suites selected by all websites in the Top Million.
query
The SQL query endpoint allows you to execute SQL queries against current and historical snapshots of the IPv4 address space and Top Million website, as well as our full collection of all seen certificates. The endpoint returns flat, paginated result sets and supports the Google BigQuery SQL syntax. Note: the SQL query end point is restricted to verified researchers.
export
The export endpoint allows exporting large subsets of data to JSON files, which can then be downloaded for further analysis. For example, if you wanted to export the full records about all hosts that still support SSLv3. Note: the export end point is restricted to verified researchers.
data
The data endpoint exposes metadata on raw data that can be downloaded from Censys. For example, if you wanted to determine whether a new dataset has been posted in a given series and how to download it.

Examples


REST Access (Raw Data). Below is a sample Python script that connects to the API and lists raw datasets that are available for download.


	import sys
	import json
	import requests

	API_URL = "https://www.censys.io/api/v1"
	UID = "login for API key"
	SECRET = "login for API secret"

	res = requests.get(API_URL + "/data", auth=(UID, SECRET))
	if res.status_code != 200:
	    print "error occurred: %s" % res.json()["error"]
	    sys.exit(1)
	for name, series in res.json()["raw_series"].iteritems():
	    print series["name"], "was last updated at", series["latest_result"]["timestamp"]

Censys Python Library. We also maintain a Python library for interacting with the API, which can be installed with Pip: pip install censys.
Below is a sample script that iterates over NSS trusted certificates:


	import censys.certificates

	UID = "login for API key"
	SECRET = "login for API secret"

	certificates = censys.certificates.CensysCertificates(UID, SECRET)
	fields = ["parsed.subject_dn", "parsed.fingerprint_sha256", "parsed.fingerprint_sha1"]

	for c in certificates.search("current_valid_nss: true"):
	    print c["parsed.subject_dn"]