1. Description

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

Peer API – API which provides historical data of downloading and sharing content using the BitTorrent protocol. Historical data is based on data from DHT network and in rare cases can be inaccurate. Facts from Peer API cannot be used as evidence. Usually we need up to 3 hours to include newly data to our Storage.

2. Connectivity

2.1. Connection type

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

2.2. IP History

You can get IP history by HTTP GET request:

where
  • host - hostname, will be provided.

  • ip - ip address which history you want to receive.

  • days - optional, search history max days ago. Default value is 14. Max value is 30.

  • contents - optional, max contents in response. Default value is 20. Max value is 100.

  • lang - optional, language of response. Default value is "en". Supported values "en" and "ru".

  • key - API Key.

Response format - Json, example:

{
  "ip": "200.55.191.39",
  "isp": "Empresa de Telecomunicaciones de Cuba, S.A.",
  "hasPorno": false,
  "hasChildPorno": false,
  "geoData": {
    "country": "Cuba",
    "city": "Havana",
    "latitude": 23.13302,
    "longitude": -82.38304
  },
  "contents": [
    {
      "category": "Movies",
      "imdbId": "tt2204340",
      "name": "Si Da Ming Bu 3 (2014) HDRip",
      "startDate": "2016-12-17T16:49:04.000Z",
      "endDate": "2016-12-10T16:49:04.000Z",
      "torrent": {
        "infohash": "71cefb01a173147094744dada9a234f43405d4ec",
        "size": 1572610110,
        "name": " Four 3 (2014) HDRip.avi"
      }
    },
    {
      "category": "Music",
      "name": "Stardust - Music Sounds Better With You (1999) 192kbps [PsychO_Path].mp3",
      "startDate": "2016-12-01T14:30:48.000Z",
      "endDate": "2016-12-10T16:49:04.000Z",
      "torrent": {
        "infohash": "70f095875b3b5ffc0d2a32503840b9c2015ea04b",
        "size": 9775296,
        "name": "Stardust - Music Sounds Better With You (1999) 192kbps [PsychO_Path].mp3"
      }
    }
  ]
}
Response JSON fields
Field Description

ip

ip address

isp

Interner Service Provider if known

hasPorno

if any content has category XXX

hasChildPorno

if any content has category "ChildPorno"

geoData

geo data for ip if known

geoData.country

ip country if known

geoData.city

ip city if known

geoData.latitude

approximately ip latitude if known

geoData.longitude

approximately ip longitude if known

contents

list of found contents

content.category

category of content if known

content.imdbId

imdbId of movie if known

content.name

name of content

content.startDate

first time when content was found in UTC

content.endDate

last time when content was found in UTC

content.torrent

torrent file information

content.torrent

torrent file information

content.torrent.infohash

infohash of torrent file. Not provided for demo key and child porn.

content.torrent.size

size of torrent file. Not provided for child porn.

content.torrent.name

name of torrent file

2.3. IP List

You can get IP list by HTTP GET request:

where
  • host - hostname, will be provided.

  • cidr - CIDR, min /18

  • key - API Key.

Response contains ip only if we have some history about it. Response format - Json, example:

{
  "CIDR" : "14.102.240.0/20",
  "peers" :
  [
    {"ip" : "14.102.240.1", "date" : "2016-12-10T16:49:04.000Z"},
    {"ip" : "14.102.240.2", "date" : "2016-12-11T16:49:04.000Z"},
    {"ip" : "14.102.240.15", "date" : "2016-12-12T16:49:04.000Z"}
  ]
}
Response JSON fields
Field Description

peers

Arrays of peers

ip

Peer ip

date

last seen date in UTC

2.4. IP Exist

You can fast check if IP exists or not in out database:

where
  • host - hostname, will be provided.

  • ip - ip address which history you want to check.

  • key - API Key.

Response contains information if we have ip. Response format - Json, example:

{
    "ip": "191.34.223.181",
    "exists": true,
    "date": "2017-03-30T03:20:50.002+0000"
}
Response JSON fields
Field Description

ip

Peer ip

exists

does we have history for this ip or nor

date

last seen date in UTC, may absent

2.5. HTTP response codes

  • 200 - OK

  • 500 - Internal server error

2.6. 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

  • INVALID_IP - value of ip is invalid

  • INVALID_DAYS - value of days is invalid

  • INVALID_CONTENTS - value of contents is invalid

  • INVALID_LANGUAGE - value of language is invalid

2.7. Content categories

  • Movies

  • Anime

  • TV

  • Music

  • Books

  • PC

  • Mobile

  • XXX

  • Child Porno

  • Unsorted