Download API¶

The Spamhaus PDNS system allows all accounts with the proper subscription tier to download hourly files of the Passive DNS traffic in the system. The history is kept for one week.

The API is exposed on the /v2/download/dumps/ endpoint and provides two methods of access.

The list method¶

The list method will enumerate all the available hourly dumps for a given day.

The URL path is /v2/download/dumps/list/:YYYYMMDD where YYYYMMDD represents the date of the day to fetch the information.

The method will return a JSON array of objects.

Each object will provide 4 properties:

date identical to the URL parameter
filename the name of the file that will be downloaded
hour represents the hour in the day when the file was generated
uid represents an unique identifier required to download the data

Note that for hour 10, the file will contain one or more dumps of the data from 09:00 to 010:00 (approximately, as the generation time depends on several factors). There may be more than one file for earch hour. In such cases, you need to download them all to have the full hourly dump.

What follows is a sample of the output of a call to this method:

[
   {
      "date":20190906,
      "filename":"deteque-pdns-2019-09-06-00.03.06.gz",
      "hour":0,
      "uid":"ccc786d2-d039-11e9-91ef-0242c0a8ff0b"
   },
   {
      "date":20190906,
      "filename":"deteque-pdns-2019-09-06-01.03.06.gz",
      "hour":1,
      "uid":"2ea5e69e-d042-11e9-8f27-0242c0a8ff0c"
   },

   ...

   },
   {
      "date":20190906,
      "filename":"deteque-pdns-2019-09-06-23.03.10.gz",
      "hour":23,
      "uid":"997286fa-d0fa-11e9-901b-0242c0a8ff0b"
   }
]

The get method¶

The get method will allow a download of single dump file. The file format is gzip (so the first thing to do after downloading is gunzipping the file in order to read the json records).

The URL path is /v2/download/dumps/get/:uid where uid is a unique identifier corresponding to the file download and obtained with the list method.

Download curl example¶

The following command will download a file identified by uuid ccc786d2-d039-11e9-91ef-0242c0a8ff0b and save it to a file named deteque-pdns-2019-09-06-00.03.06.gz

curl --header "Authorization: Bearer <TOKEN>" \
     -o deteque-pdns-2019-09-06-00.03.06.gz \
      https://api-pdns.spamhaustech.com/v2/download/dumps/get/ccc786d2-d039-11e9-91ef-0242c0a8ff0b