1. Description

This document is intended to serve software developers as an implementation guide for integration with Capture API.

Capture API provides verified data about peers activity in BitTorrent network in real time.

All peers collected via DHT are checking with set of Capture Filters for capturing. Capture Filter is the rule to define which peer should be captured. Basic attributes of Capture Filters:

  • infohashes - optional. List of torrent info hashes to capture

  • subnets - optional. List of subnets in CIDR format

  • countries - optional. List of country codes in ISO 3166-1 alpha-2

  • storeTCPDumpFile - optional. Should TCP dump be stored or not.

Capture Filter is created by our manager but you can managed it via this API. If peer should be captured then system connects to it via Bittorrent protocol, makes initial handshake and stores all captured data and TCP dump in Pcap format if needed. As the result you can receive it in realtime over email or RabbitMQ or request it via REST.

2. Connectivity

2.1. Connection type

Connection to Capture API is available over the HTTPS protocol based on REST. Every request that your application sends to the Capture API needs to contain API key as parameter key. Please request API key from your manager.

Realtime notifications are available over email or RabbitMQ.

2.2. Captured Peers History

You can get captured peers history by HTTP GET request:

https://{host}/capture/peers/all?from={from}&to={to}&filter={filter}&success={success}&key={key}

where

  • host - hostname, will be provided.

  • from - from timestamp, in milliseconds.

  • to - desired to timestamp, in milliseconds.

  • filter - Capture Filter name, will be provided by your manager.

  • success - optional boolean (true/false), return only successfully/unsuccessfully captured peers.

  • key - API Key.

cURL examples:

# Request all data from 2018-06-16 21:00:00 UTC to 2018-06-17 21:00:00 UTC for Capture Filter yourFilterName
curl -X GET "https://{host}/capture/peers/all/?key=yourkey&from=1529182800000&to=1529269200000&filter=yourFilterName"

# Request successfully captured data from 2018-06-16 21:00:00 UTC to 2018-06-17 21:00:00 UTC for Capture Filter yourFilterName
curl -X GET "https://{host}/capture/peers/all/?key=yourkey&from=1529182800000&to=1529269200000&filter=yourFilterName&success=true"

Response format - Json, example:

{
  "from": 1529182800000,
  "to": 1529252207000000,
  "hasMore": false,
  "peers": [
    {
      "date": "2018-06-17T05:58:36.000+0000",
      "ip": "46.19.68.144",
      "port": 39716,
      "infohash": "d059053fd7122a95408346147b1edc0193432a0c",
      "countryCode": "RU",
      "city": "Vladivostok",
      "isp": "Joint Stock Company Artemovskoye Interaktivnoe Tel",
      "captureReport": {
        "date": "2018-06-17T05:59:01.000+0000",
        "totalPiecesInTorrent": 3053,
        "hasTotal": true,
        "hasPieces": 3053,
        "clientName": "BitTorrent 7.10",
        "hostIdentifier": "ipn-46-19-68-144.artem-catv.ru"
      }
    },
    {
      "date": "2018-06-17T05:58:41.000+0000",
      "ip": "79.120.64.38",
      "port": 51777,
      "infohash": "d059053fd7122a95408346147b1edc0193432a0c",
      "countryCode": "RU",
      "city": "Moscow",
      "isp": "Net By Net Holding LLC",
      "captureReport": {
        "date": "2018-06-17T05:58:47.000+0000",
        "totalPiecesInTorrent": 3310,
        "hasTotal": false,
        "hasPieces": 1784,
        "clientName": "libTorrent 0.13.2",
        "hostIdentifier": "79.120.64.38"
      }
    }
  ]
}
Response JSON fields
Field Description

from

from timestamp in milliseconds

to

real to timestamp in milliseconds. Could be different from desired to timestamp from request

hasMore

flag that there are more peers any you should repeat this request with from=real to and to=desired to

peers

list of captured peers

peers.date

datetime when peer was found in DHT, in UTC

peers.ip

ip address of peer

peers.port

Bittorrent protocol port of peer

peers.infohash

info hash of seeded torrent

peers.countryCode

ISO 3166-1 alpha-2 country code

peers.city

approximate city of peer

peers.isp

approximate ISP of peer

peers.captureReport

optional, in case of successed capturing

peers.captureReport.date

time when capture report was done, in UTC

peers.captureReport.totalPiecesInTorrent

total pieces in torrent

peers.captureReport.hasPieces

how many pieces peer has

peers.captureReport.hasTotal

has peer all pieces (seeder) or not (leacher)

peers.captureReport.clientName

peer client name

peers.captureReport.hostIdentifier

peer reverse DNS name if known

peers.captureError

error description if no CaptureReport

2.3. List of Capture Filters

You can get list of your Capture Filters by HTTP GET request:

https://{host}/capture/filters?key={key}

where

  • key - API Key.

Response format - Json, example:

{
  "filters": [
    {
      "name": "CaptureFilter1",
      "description": "Opensource OS",
      "infohashes": [
        "2b90241f8e95d53cacf0f8c72a92e46b57911600",
        "78957ab8fc0b27f3c1abf0953d0daba66c347d12",
        "34ad2e64fcba386a1c26f77f1dc1bbd275057f0f",
        "15e9b65ad41512c8aba56ecb1d83b53992fc1113"
      ],
      "subnets": [],
      "countryCodes": [
        "US"
      ],
      "storeTCPDumpFile": true,
      "storeTCPDumpAttempt": true,
      "enabled": true
    }
  ]
}
Response JSON fields
Field Description

filters.name

unique name of Capture Filter

filters.description

human readable description of Capture Filter

filters.infohashes

list of info hashes of torrent to capture. Empty for all

filters.subnets

list of CIDR subnets to capture. Empty for all

filters.countryCodes

list of country codes to capture. Empty for all

filters.storeTCPDumpFile

should Pcap TCP dump be stored or not

filters.storeTCPDumpAttempt

should unsuccessful attepmt of capture be stored or not

filters.enabled

is Capture Filter enabled

2.4. Add Info Hash to Capture Filter

You can add new Info Hash to your Capture Filter by HTTP POST request:

https://{host}/capture/filters/addInfohash

POST parameters

  • key - API Key.

  • filter - Capture Filter name.

  • infohash - Torrent info hash.

cURL example:

curl --data "key=yourKey&filter=yourFilterName&infohash=503c73b73405f950ae9f63555df9c6255acafcd0" https://{host}/capture/filters/addInfohash/

Response contains HTTP 200 OK and empty Json if added.

Note
 Our system should have info hash and downloaded and parsed torrent file before adding it to Capture Filter. It’s recommended to add torrent file with Add Torrent from TorrentAPI. Also you could add only info hash with Add Infohash method but in that case you have to wait while torrent file will be downloaded by our system.

2.5. Delete Info Hash from Capture Filter

You can delete Info Hash from your Capture Filter by HTTP POST request:

https://{host}/capture/filters/deleteInfohash

POST parameters

  • key - API Key.

  • filter - Capture Filter name.

  • infohash - Torrent info hash.

cURL example:

curl --data "key=yourKey&filter=yourFilterName&infohash=503c73b73405f950ae9f63555df9c6255acafcd0" https://{host}/capture/filters/deleteInfohash/

Response contains HTTP 200 OK and empty Json if deleted.

Note
 There are should be at least 1 info hash in Capture Filter, you cannot delete all info hashes from it.

2.6. HTTP response codes

  • 200 - OK

  • 500 - Internal server error

2.7. Error response

In case of error response body contains error and message:

{
    error: "API_KEY_UNKNOWN",
    message: "API Key is unknown",
}
possible error values (new can be added later)

  • API_KEY_UNKNOWN - API key is unknown

  • API_KEY_SUSPENDED - API key is suspended

  • ACCESS_FORBIDDEN - API key doen’t provide access to method

  • INVALID_INFOHASH - value of infohash is invalid

  • INFOHASH_NOT_FOUND - torrent with infohash not found in our database

  • TORRENT_FILE_NOT_FOUND - torrent file is not found for existed infohash in our database

  • FILTER_NOT_FOUND - Capture Filter not found

  • FILTER_WITHOUT_INFOHASHES_NOT_ALLOWED - Capture Filter should have at least one info hash