Raw Data API


The Raw Data API exposes metadata on the raw data that can be downloaded from Censys. There are several endpoints, which allow you to get the list of all scan series (Get Series), get details on a particular series (View Series), and get details on a particular scan within a series (View Result).

Get Series


Description

The Get Series endpoint returns a data on the types of scans we regularly perform ("series").

Endpoint
GET /api/v1/data
URL Parameters
(none)
Data Parameters
(none)
Success Response
200 SUCCESS
We were able to successfully retrieve a list of series.
Example:
{
  "primary_series": {
    "certificates": {
      "description": "[...]",
      "details_url": "https:\/\/censys.io\/api\/v1\/data\/certificates",
      "latest_result": {
        "timestamp": "20151013T120047",
        "name": "20151013T1200",
        "details_url": "https:\/\/censys.io\/api\/v1\/data\/certificates\/20151013T1200"
      },
      "id": "certificates",
      "name": "certificates"
    },
    "domain": {
      "description": "[...]",
      "details_url": "https:\/\/censys.io\/api\/v1\/data\/domain",
      "latest_result": {
        "timestamp": "20151013T235310",
        "name": "20151013T2353",
        "details_url": "https:\/\/censys.io\/api\/v1\/data\/domain\/20151013T2353"
      },
      "id": "domain",
      "name": "domain"
    },
    "ipv4": {
      "description": "[...]",
      "details_url": "https:\/\/censys.io\/api\/v1\/data\/ipv4",
      "latest_result": {
        "timestamp": "20151013T055229",
        "name": "20151013T0552",
        "details_url": "https:\/\/censys.io\/api\/v1\/data\/ipv4\/20151013T0552"
      },
      "id": "ipv4",
      "name": "ipv4"
    }
  },
  "raw_series": {
    "22-ssh-banner-full_ipv4": {
      "subprotocol": "banner",
      "description": "[...]",
      "protocol": "ssh",
      "name": "22-ssh-banner-full_ipv4",
      "details_url": "https:\/\/censys.io\/api\/v1\/data\/22-ssh-banner-full_ipv4",
      "latest_result": {
        "timestamp": "20150930T005634",
        "name": "20150930T0056",
        "details_url": "https:\/\/censys.io\/api\/v1\/data\/22-ssh-banner-full_ipv4\/20150930T0056"
      },
      "destination": "full_ipv4",
      "id": "22-ssh-banner-full_ipv4",
      "port": 22
    },

    [...]

    "443-https-ssl3-alexa_top1mil": {
      "subprotocol": "ssl3",
      "description": "[...]",
      "protocol": "https",
      "name": "443-https-ssl3-alexa_top1mil",
      "details_url": "https:\/\/censys.io\/api\/v1\/data\/443-https-ssl3-alexa_top1mil",
      "latest_result": {
        "timestamp": "20150727T060848",
        "name": "20150727T0608",
        "details_url": "https:\/\/censys.io\/api\/v1\/data\/443-https-ssl3-alexa_top1mil\/20150727T0608"
      },
      "destination": "alexa_top1mil",
      "id": "443-https-ssl3-alexa_top1mil",
      "port": 443
    }
}
Error Responses
  • 429 RATE LIMIT EXCEEDED
    The requested record was not retreived because you have execeeded your specified rate limit.
    Example:
    {"error_code":429, "error":"rate limit exceeded"}
  • 500 INTERNAL SERVER ERROR
    An unexpected error occurred when trying retreive raw data. Try again at a later time or contact us at requests@censys.io if the problem persists.
    Example:
    {"error_code":500, "error":"unknown error occurred"}

View Series


Description

The View Series endpoint returns data we have about a particular series—a scan of the same protocol and destination accross time—including the list of scans.

Endpoint
GET /api/v1/data/:series
URL Parameters
  • series [required string]
    The ID of the series, e.g., 22-ssh-banner-full_ipv4.
Example: /api/v1/data/22-ssh-banner-full_ipv4
Data Parameters
(none)
Success Response
200 SUCCESS
We were able to successfully retrieve a list of series.
Example:
{
  "id": "22-ssh-banner-full_ipv4",
  "port": 22
  "protocol": "ssh",
  "subprotocol": "banner",
  "destination": "full_ipv4",
  "name": "22-ssh-banner-full_ipv4",
  "description": "This dataset is composed of a ZMap TCP SYN scan on port 21 and a ZGrab SSH Banner Grab\r\nfor the for responsive hosts. The connection is terminated after a banner has been\r\nreceived. We do not currently capture SSH host keys, but we are planning to add this\r\nfunctionality in the future.",
  "results": {
    "historical": [
      {
        "timestamp": "20150912T132919",
        "id": "20150912T1329",
        "details_url": "https:\/\/censys.io\/api\/v1\/data\/22-ssh-banner-full_ipv4\/20150912T1329"
      },

      [...]

      {
        "timestamp": "20150930T005634",
        "id": "20150930T0056",
        "details_url": "https:\/\/censys.io\/api\/v1\/data\/22-ssh-banner-full_ipv4\/20150930T0056"
      }
    ],
    "latest": {
      "timestamp": "20150930T005634",
      "id": "20150930T0056",
      "details_url": "https:\/\/censys.io\/api\/v1\/data\/22-ssh-banner-full_ipv4\/20150930T0056"
    }
  }
}
Error Responses
  • 404 NOT FOUND
    The requested series does not exist.
    Example:
    {"error_code":404, "error":"page not found"}
  • 429 RATE LIMIT EXCEEDED
    The requested record was not retreived because you have execeeded your specified rate limit.
    Example:
    {"error_code":429, "error":"rate limit exceeded"}
  • 500 INTERNAL SERVER ERROR
    An unexpected error occurred when trying to execute your query. Try again at a later time or contact us at requests@censys.io if the problem persists.
    Example:
    {"error_code":500, "error":"unknown error occurred"}

View Result


Description

The View Result endpoint returns data on a particular scan ("result"), as found in the Get Series or View Series endpoints.

Endpoint
GET /api/v1/data/:series/:result
URL Parameters
  • series [required string]
    The ID of the series, e.g., 22-ssh-banner-full_ipv4.
  • result [required string]
    The ID of the result, e.g., 20150930T0056.
Example: /api/v1/data/22-ssh-banner-full_ipv4/20150930T0056
Data Parameters
(none)
Success Response
200 SUCCESS
We were able to successfully retrieve a list of series.
Example:
{
  "id": "20150930T0056",
  "timestamp": "20150930T005634",
  "files": {
    "zmap-results": {
      "file_type": "csv",
      "schema": null,
      "download_path": "https:\/\/storage.googleapis.com\/zsearch-22-ssh-banner-full_ipv4\/22-ssh-banner-full_ipv4-20150929T040000\/22-ssh-banner-full_ipv4-20150929T040000-zmap-results.csv",
      "sha256_fingerprint": "693b6bdd6b954aed3981ca9d801bb1317bfdb19f560f968781823b9abef8eaa3",
      "size": 304
    },
    "zgrab-results": {
      "file_type": "json",
      "schema": {
        "timestamp": {
          "type": "date"
        },

        [...]

        "ip": {
          "type": "ip"
        }
      }
    },
    "download_path": "https:\/\/storage.googleapis.com\/zsearch-22-ssh-banner-full_ipv4\/22-ssh-banner-full_ipv4-20150929T040000\/22-ssh-banner-full_ipv4-20150929T040000-zgrab-results.json",
    "sha256_fingerprint": "cdd962fe956674749ef5d40d59c423a0be77432a246bcd223c3346576c9479ff",
    "size": 21707
  }
}
Error Responses
  • 404 NOT FOUND
    The requested series or result does not exist.
    Example:
    {"error_code":404, "error":"page not found"}
  • 429 RATE LIMIT EXCEEDED
    The requested record was not retreived because you have execeeded your specified rate limit.
    Example:
    {"error_code":429, "error":"rate limit exceeded"}
  • 500 INTERNAL SERVER ERROR
    An unexpected error occurred when trying to execute your query. Try again at a later time or contact us at requests@censys.io if the problem persists.
    Example:
    {"error_code":500, "error":"unknown error occurred"}