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 address |
|
Interner Service Provider if known |
|
if any content has category XXX |
|
if any content has category "ChildPorno" |
|
geo data for ip if known |
|
ip country if known |
|
ip city if known |
|
approximately ip latitude if known |
|
approximately ip longitude if known |
|
list of found contents |
|
category of content if known |
|
imdbId of movie if known |
|
name of content |
|
first time when content was found in UTC |
|
last time when content was found in UTC |
|
torrent file information |
|
torrent file information |
|
infohash of torrent file. Not provided for demo key and child porn. |
|
size of torrent file. Not provided for child porn. |
|
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 |
---|---|
|
Arrays of peers |
|
Peer ip |
|
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 |
---|---|
|
Peer ip |
|
does we have history for this ip or nor |
|
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