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 ```