github.com/predbdotovh/pre-api@v0.0.0-20211230223408-096f265fde6a/docs/index.md (about)

     1  # Predb.ovh API documentation
     2  
     3  Most pre databases websites do not allow data scapping, nor do they offer an API.
     4  
     5  Having a easily accessible API was a requirement for me, so I built this one using public pre sources.
     6  
     7  ## Disclaimers
     8  
     9  Disclaimer : This API has been built for my personal usage, and may not fit your needs.
    10  [Github issues](https://github.com/predbdotovh/pre-api/issues) can be filled, but don't expect too much.
    11  
    12  Disclaimer 2 : Once again, this API does **NOT** host any content, only metadata associated to scene releases.
    13  
    14  Disclaimer 3 : Don't know what scene releases are ? You're probably at the wrong place.
    15  
    16  ## Status
    17  
    18  This API is currently usable, and used by [demo website](https://predb.ovh/) which is
    19  also [open-sourced](https://github.com/predbdotovh/website-vuejs).
    20  
    21  As the API is fed by Sphinx, results are hard limited at 1000, and I don't expect to modify this behaviour in the
    22  future.
    23  
    24  A monthly-ish sql dump is available here : [https://predb.ovh/download/](https://predb.ovh/download/)
    25  
    26  ## API versions
    27  
    28  Current version is **v1**. This version is expected to be updated on each breaking change.
    29  
    30  Current base URL is : [https://predb.ovh/api/v1/](https://predb.ovh/api/v1/)
    31  
    32  ## Responses
    33  
    34  The API will always return HTTP 200 with application/json content (except for [RSS](#get-rss)).
    35  
    36  On success :
    37  
    38  ```
    39  {
    40      "status": "success",
    41      "message": "",
    42      "data": "... See endpoints responses ..."
    43  }
    44  ```
    45  
    46  On failure :
    47  
    48  ```
    49  {
    50      "status": "error",
    51      "message": "Human readable error message",
    52      "data": null
    53  }
    54  ```
    55  
    56  ## Endpoints
    57  
    58  ### GET /
    59  
    60  List releases matching a set of filters given in parameters
    61  
    62  - Cache : 60 seconds
    63  - Usage : Get releases info
    64  - Rate limit : 30/60s
    65  
    66  #### Parameters
    67  
    68  All parameters are optional
    69  
    70  | param key | type   | content                              |
    71  | --------- | ------ | ------------------------------------ |
    72  | count     | int    | Maximum releases count expected      |
    73  | page      | int    | Page offset                          |
    74  | offset    | int    | Row offset (overwrites page param)   |
    75  | q         | string | Query                                |
    76  | id        | int    | Specific pre ID (overwrites q param) |
    77  
    78  Query is directly fed to a SphinxSearch engine,
    79  allowing [specific syntax](http://sphinxsearch.com/docs/current/extended-syntax.html). Note: cat and team are indexed,
    80  allowing fast queries like
    81  [https://predb.ovh/api/v1/?q=@cat%20EBOOK](https://predb.ovh/api/v1/?q=@cat%20EBOOK)
    82  
    83  #### Response
    84  
    85  ##### Data
    86  
    87  | json key | type      | content                       |
    88  | -------- | --------- | ----------------------------- |
    89  | rowCount | int       | Count of rows returned        |
    90  | offset   | int       | Row count offset requested    |
    91  | reqCount | int       | Row count requested           |
    92  | total    | int       | Total matching rows           |
    93  | time     | float     | Request internal duration     |
    94  | rows     | []release | Array of [releases](#release) |
    95  
    96  ##### Release
    97  
    98  | json key | type      | content                           |
    99  | -------- | --------- | --------------------------------- |
   100  | id       | int       | Internal unique pre ID            |
   101  | name     | string    | Release name                      |
   102  | team     | string    | Release group extracted from name |
   103  | cat      | string    | Category                          |
   104  | genre    | string    | Genre                             |
   105  | url      | string    | Info link                         |
   106  | size     | float     | Release size in kb                |
   107  | files    | int       | Original file count               |
   108  | preAt    | int       | Release pre timestamp             |
   109  | nuke     | nuke/null | [Nuke](#nuke) info if available   |
   110  
   111  ##### Nuke
   112  
   113  | json key | type   | content                     |
   114  | -------- | ------ | --------------------------- |
   115  | id       | int    | Internal unique nuke ID     |
   116  | typeId   | int    | [Nuke type](#nuke-types) ID |
   117  | type     | string | [Nuke type](#nuke-types)    |
   118  | preId    | int    | Nuked pre ID                |
   119  | reason   | string | Nuke reason                 |
   120  | net      | string | Nuke source net             |
   121  | nukeAt   | int    | Nuke timestamp              |
   122  
   123  ##### Nuke types
   124  
   125  Known nuke types and type ids
   126  
   127  | nuke type ID | nuke type |
   128  | ------------ | --------- |
   129  | 1            | nuke      |
   130  | 2            | unnuke    |
   131  | 3            | modnuke   |
   132  | 4            | delpre    |
   133  | 5            | undelpre  |
   134  
   135  #### Example
   136  
   137  - [https://predb.ovh/api/v1/?q=bdrip](https://predb.ovh/api/v1/?q=bdrip)
   138  
   139  ```
   140  {
   141      "status": "success",
   142      "message": "",
   143      "data": {
   144          "rowCount": 20,
   145          "rows": [
   146              {
   147                  "id": 7813747,
   148                  "name": "Fortitude.S02E10.German.DUBBED.BDRip.x264-AIDA",
   149                  "team": "AIDA",
   150                  "cat": "TV-DVDRIP",
   151                  "genre": "",
   152                  "url": "http://imdb.com/title/tt3498622/",
   153                  "size": 0,
   154                  "files": 0,
   155                  "preAt": 1493815560,
   156                  "nuke": null
   157              },
   158              {
   159                  "snip": "Content snipped for lisibility"
   160              },
   161              {
   162                  "id": 7812994,
   163                  "name": "Fortitude.S02E07.BDRip.x264-HAGGiS",
   164                  "team": "HAGGiS",
   165                  "cat": "TV-DVDRIP",
   166                  "genre": "",
   167                  "url": "http://imdb.com/title/tt3498622",
   168                  "size": 258,
   169                  "files": 19,
   170                  "preAt": 1493762423,
   171                  "nuke": null
   172              }
   173          ],
   174          "offset": 0,
   175          "reqCount": 20,
   176          "total": 70729,
   177          "time": 0.108095174
   178      }
   179  }
   180  ```
   181  
   182  ### GET /live
   183  
   184  This method is the exact clone of [GET /](#get), without any HTTP cache.
   185  
   186  - Cache : None
   187  - Usage : Get fresh data before listening to websocket updates
   188  - Rate limit : 2/20s
   189  
   190  **To avoid abuse, this method is severly rate limited**
   191  
   192  #### Example
   193  
   194  - [https://predb.ovh/api/v1/live](https://predb.ovh/api/v1/live)
   195  
   196  ```
   197  {
   198      "status": "success",
   199      "message": "",
   200      "data": {
   201          "rowCount": 20,
   202          "rows": [
   203              {
   204                  "id": 7814699,
   205                  "name": "AllOver30.com_17.05.03.Drew.Jones.XXX.iMAGESET-YAPG",
   206                  "team": "YAPG",
   207                  "cat": "XXX-iMGSET",
   208                  "genre": "Mature.Women",
   209                  "url": "http://HTTP://AllOver30.com",
   210                  "size": 211.9,
   211                  "files": 45,
   212                  "preAt": 1493881734,
   213                  "nuke": null
   214              },
   215              {
   216                  "snip": "Content snipped for lisibility"
   217              },
   218              {
   219                  "id": 7814680,
   220                  "name": "Robert_Abigail_Feat_13_Amps_-_Living_On_The_Right_Side-(AG_010)-WEB-2017-ZzZz",
   221                  "team": "ZzZz",
   222                  "cat": "MP3",
   223                  "genre": "Dance",
   224                  "url": "http://junodownload.com",
   225                  "size": 7,
   226                  "files": 1,
   227                  "preAt": 1493880783,
   228                  "nuke": null
   229              }
   230          ],
   231          "offset": 0,
   232          "reqCount": 20,
   233          "total": 7751247,
   234          "time": 0.898239015
   235      }
   236  }
   237  ```
   238  
   239  ### GET /rss
   240  
   241  This method is the exact clone of [GET /](#get), formatted using RSS2.0 spec.
   242  
   243  - Cache : 60 seconds
   244  - Usage : Get releases info using a RSS reader
   245  - Rate limit : 30/60s
   246  
   247  #### Example
   248  
   249  - [https://predb.ovh/api/v1/rss](https://predb.ovh/api/v1/rss)
   250  
   251  ```
   252  <?xml version="1.0" encoding="UTF-8"?>
   253  <rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">
   254      <channel>
   255          <title>PreDB</title>
   256          <link>https://predb.ovh/</link>
   257          <description></description>
   258          <pubDate>Sun, 15 Dec 2019 21:23:59 +0100</pubDate>
   259          <item>
   260              <title>Le.Steppe.Dell.Asia.La.Piu.Grande.Steppa.Della.Terra.iTALiAN.HDTV.x264-iDiB</title>
   261              <link>https://predb.ovh/?id=9643108</link>
   262              <description>Cat:TV-SD-X264 | Genre: | Size:0MB | Files:0 | ID:9643108</description>
   263              <pubDate>Sun, 15 Dec 2019 21:23:49 +0100</pubDate>
   264          </item>
   265          <item>
   266              <title>Le.Steppe.Dell.Asia.La.Piu.Grande.Steppa.Della.Terra.iTALiAN.720p.HDTV.x264-iDiB</title>
   267              <link>https://predb.ovh/?id=9643107</link>
   268              <description>Cat:TV-HD-X264 | Genre: | Size:0MB | Files:0 | ID:9643107</description>
   269              <pubDate>Sun, 15 Dec 2019 21:23:48 +0100</pubDate>
   270          </item>
   271      </channel>
   272  </rss>
   273  ```
   274  
   275  ### GET /teams
   276  
   277  Teams stats with first and latest pre, and total recorded pre.
   278  
   279  This is currently hard limited to 1000 results, may be subject to change if necessary.
   280  
   281  - Cache : 3600 seconds
   282  - Usage : Teams statistics
   283  
   284  #### Parameters
   285  
   286  None
   287  
   288  #### Response
   289  
   290  ##### Data
   291  
   292  | json key | type      | content                       |
   293  | -------- | --------- | ----------------------------- |
   294  | rowCount | int       | Count of rows returned        |
   295  | offset   | int       | Row count offset requested    |
   296  | reqCount | int       | Row count requested           |
   297  | total    | int       | Total matching rows           |
   298  | time     | float     | Request internal duration     |
   299  | rows     | []team    | Array of [teams](#team)       |
   300  
   301  ##### Team
   302  
   303  | json key  | type      | content                               |
   304  | --------- | --------- | ------------------------------------- |
   305  | team      | string    | Release group name                    |
   306  | firstPre  | int       | First recorded release pre timestamp  |
   307  | latestPre | int       | Latest recorded release pre timestamp |
   308  | count     | int       | Total team pre count                  |
   309  
   310  #### Example
   311  
   312  - [https://predb.ovh/api/v1/teams](https://predb.ovh/api/v1/teams)
   313  
   314  ```
   315  {
   316      "status": "success",
   317      "message": "",
   318      "data": {
   319          "rowCount": 1000,
   320          "rows": [
   321              {
   322                  "team": "KTR",
   323                  "firstPre": 1203561700,
   324                  "latestPre": 1598341396,
   325                  "count": 307933
   326              },
   327              {
   328                  "snip": "Content snipped for lisibility"
   329              },
   330          ],
   331          "time": 5.465514844
   332      }
   333  }
   334  ```
   335  
   336  ### GET /stats
   337  
   338  Basic stats about internal database health.
   339  
   340  - Cache : 60 seconds
   341  - Usage : Keep track of current database status and response times
   342  
   343  #### Parameters
   344  
   345  None
   346  
   347  #### Response
   348  
   349  ##### Data
   350  
   351  | json key | type   | content                             |
   352  | -------- | ------ | ----------------------------------- |
   353  | total    | int    | Total indexed releases count        |
   354  | date     | string | Current RFC3339 timestamp of server |
   355  | time     | int    | Full index scan duration            |
   356  
   357  #### Example
   358  
   359  - [https://predb.ovh/api/v1/stats](https://predb.ovh/api/v1/stats)
   360  
   361  ```
   362  {
   363      "status": "success",
   364      "message": "",
   365      "data": {
   366          "total": 7751280,
   367          "date": "2017-05-04T09:49:42.527504724+02:00",
   368          "time": 0.893255737
   369      }
   370  }
   371  ```
   372  
   373  ### GET /ws
   374  
   375  A websocket endpoint, sending near realtime updates. To use this, you need to bind using
   376  a [Websocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications).
   377  
   378  - Cache : None
   379  - Usage : Realtime updates
   380  
   381  #### Parameters
   382  
   383  There is no parameter, and any input on the websocket is discarded
   384  
   385  #### Response
   386  
   387  There is no response per se, but a range of frames sent over time
   388  
   389  ##### Frame
   390  
   391  Each frame represents an action towards a specific release.
   392  
   393  | json key | type    | content             |
   394  | -------- | ------- | ------------------- |
   395  | action   | string  | Action type         |
   396  | row      | release | [Release](#release) |
   397  
   398  ##### Action types
   399  
   400  Known action types
   401  
   402  | action   | context                                 |
   403  | -------- | --------------------------------------- |
   404  | insert   | First release pre                       |
   405  | update   | Any release field update                |
   406  | delete   | Erroneous release (should never happen) |
   407  | nuke     | Release nuked by net                    |
   408  | unnuke   | Release unnuked by net                  |
   409  | modnuke  | Nuke reason modified by net             |
   410  | delpre   | Pre deleted by net                      |
   411  | undelpre | Pre undeleted by net                    |
   412  
   413  #### Example
   414  
   415  - [https://predb.ovh/api/v1/ws](https://predb.ovh/api/v1/ws)
   416  
   417  ```
   418  {
   419      "action": "insert",
   420      "row": {
   421          "id": 7814727,
   422          "name": "Doom_Squad-Countdown_To_Doomsday_II-WEB-2016-ESG",
   423          "team": "ESG",
   424          "cat": "MP3",
   425          "genre": "",
   426          "url": "",
   427          "size": 0,
   428          "files": 0,
   429          "preAt": 1493884429,
   430          "nuke": null
   431      }
   432  }
   433  ```