-
Notifications
You must be signed in to change notification settings - Fork 179
/
newznab_api_specification.txt
executable file
·819 lines (669 loc) · 40.9 KB
/
newznab_api_specification.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
newznab Usenet Searching Web API
v0.5
2015-10-24
Authors:
ensi ensisoft@gmail.com
newznab http://newznab.com/
nZEDb https://github.com/nZEDb/nZEDb
1. Introduction
2. Functions
2.1 CAPS
2.2 REGISTER
2.3 SEARCH
2.4 TV-SEARCH
2.5 MOVIE-SEARCH
2.6 DETAILS
3. Predefined Categories
4. Predefined Attributes
4.1 List of Attributes
4.2 Attribute example
5. nZEDb Error Codes
5.1 Error code example
6 Changelog
1. Introduction
This document describes the newznab/nZEDb Usenet Searching Web API. The API is designed to be implemented
by Usenet indexing sites, i.e. sites that index Usenet newsgroups through some means, typically
by downloading and inspecting the NNTP headers. The API is aimed for NZB aware client applications
to allow them to perform Usenet searches against nZEDb servers and receive NZB information in order
to facilitate direct downloading from Usenet without having to download any NNTP headers.
This document does not describe the actual implementation of either the client or the server but just
describes the HTTP(S) interface and request/response sequences.
Intended readers are server and client implementers.
1.1 Notation
This document uses the following notations:
Parameters: "t=c" denotes a required HTTP query parameter. [o=json | o=xml] denotes optional
parameters with possible values.
2. Functions
All functions are executed as HTTP(S) requests over TCP. All parameters are to be passed
as query parameters unless otherwise indicated. All returned XML/JSON data is UTF-8 encoded
unless otherwise specified. All query parameters should be UTF-8 and URL encoded, i.e.
query-param = URL-ENCODE(UTF8-ENCODE(param=value)).
The functions are divided into two categories. Functions specific to searching and retrieving of items
and the their information such as SEARCH and TV-SEARCH and functions that are for site/user account
management such as CAPS and REGISTER.
Any conforming implementation should support the CAPS and SEARCH functions. Other functions are optional
and if not supported will return the "203 Function Not Available" when invoked.
2.1 CAPS
Description:
CAPS function is used to query the server for supported features and the protocol version and other
meta data relevant to the implementation. This function does not require the client to provide any
login information but can be executed out of "login session".
Important fields of the returned data:
server/version The version of the protocol implemented by the server. All implementations should be backwards compatible.
limits The limit and defaults to the number of search results returned.
retention Server retention (how many days NZB information is stored before being purged).
category Defines a searchable category which might have any number of subcategories.
category/id Unique category ID, can be either one of the standard category IDs or a site specific ID.
category/name Any descriptive name for the category. Can be site/language specific.
category/description A description of the contents of the category.
category/subcat A subcategory.
category/subcat/id/ Unique category ID, can be either one of the standard category IDs or a site specific ID.
category/subcat/name Any descriptive name for the category. Can be site/language specific.
category/subcat/description A description of the contents of the category.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=caps Caps function, must always be "caps".
Optional parameters:
o=xxx Output format, either "JSON" or "XML. Default is "XML".
Examples:
--> GET http://servername.com/api?t=caps
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<caps>
<!-- server information -->
<server version="1.0" title="nZEDb" strapline="A great usenet indexer"
email="info@nZEDb.com" url="http://servername.com/" image="http://servername.com/theme/black/images/banner.jpg"/>
<!-- limit parameter range -->
<limits max="100" default="50"/>
<!-- the server NZB retention -->
<retention days="400"/>
<!-- registration available or not -->
<registration available="yes" open="yes" />
<!--
The search functions available at the server
The only currently defined search functions are SEARCH and TV-SEARCH.
Any conforming implementation should at least support the basic search.
Other search functions are optional.
-->
<searching>
<search available="yes" supportedParams="q,group"/>
<tv-search available="yes" supportedParams="q,rid,tvdbid,vid,traktid,tvmazeid,imdbid,tmdbid,season,ep"/>
<movie-search available="yes" supportedParams="q,imdbid"/>
<audio-search available="no" supportedParams=""/>
</searching>
<!-- supported categories -->
<categories>
<category id="1000" name="Console">
<subcat id="1010" name="NDS"/>
<subcat id="1020" name="PSP"/>
</category>
<category id="2000" name="Movies">
<subcat id="2010" name="Foreign"/>
</category>
<!-- site specific categories -->
<category id="1000001" name="MotoGP" description="Latest MotoGP stuff"/>
<category id="1000002" name="Fifa 2010" description="Fifa 2010 world cup">
<subcat id="1000003" name="Fifa 2010 HD" description="HD stuff"/>
<subcat id="1000004" name="Fifa 2010 SD" description="SD stuff"/>
</category>
<!-- etc.. -->
</categories>
</caps>
</xml>
2.2 REGISTER
Description:
REGISTER function is used for automatically creating and registering user account.
This is an optional function and may or may not be available at a site. It is also possible
that function is available but currently registrations at the site are closed.
The only prerequisite for registering an account is a valid email address and any server policies.
It is at the server administration discretion to allow or deny registrations based on
for example the validity of the email address or the the current client host address.
On successful registration a valid username, password and api key are returned to the caller
On error an appropriate error code is returned.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=register Register function, must always be "register"
email=xxx A valid email address to be used for registration. (URL/UTF-8 encoded).
Examples:
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<register username="user123" password="pass123" apikey="abcabcd11234abc"/>
</register>
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<error code="103" description="Registration denied"/>
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<error code="104" description="No more registrations allowed"/>
--> GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<error code="203" description="Function not available"/>
2.3 SEARCH
Description:
SEARCH function searches the index for items matching the search criteria. On successful
search the response contains a list of found items. Even if search matched nothing an empty
response set is created and returned. This function requires passing the user credentials.
Searches that include categories that are not supported by the server are still executed
but the non-supported categories are simply skipped. This basically treats such a search
simply as a "no match" but allows the same query to be ran simultaneously against several
servers.
The list of search categories specifies a logical OR condition. I.e. an item matching the
search input in any of the specified categories is considered a match and is returned. E.g.
a search searching for "linux" in "computer" and "ebook" categories searches for matching
items in "computer" and "ebook" but does not search for example the "movies" category.
Items found in either group are then combined into a single result set. If the input string
for search is empty all items (within the server/query limits) are returned for the
matching categories.
When performing the query the categories to be searched are concatenated into a single
query parameter by , (comma). For example "cat=200,300,400", which is then URL encoded.
The returned XML data stream is RSS 2.0 compliant and also contains additional information
in the extra namespace.
Response-offset field identifies the current subset of all the matches that are being
transmitted in the response. In other words, if a search for "disco" finds more matches
than the server is capable of transmitting in a single response, the response needs to be
split into several responses. Then it is the clients responsibility to repeat the same
query with same parameters but specify an increased offset in order to return the next
set of results.
If offset query parameter is not used response data contains items between 0 offset - limit.
If offset query parameter is out of bounds an empty result set is returned.
Important fields of the returned data (RSS):
title Title of the found item.
guid A globally unique (GUID) item identifier.
pubdate The publishing date in RSS date object as specified by RFC822/2822. (not the Usenet date)
category The category the NZB belongs to. (This is human readable for RSS. More precise category is found in additional data)
enclosure The NZB url
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=search Search function, must always be "search"
apikey=xxxx User's key as provided by the service provider.
Optional parameters:
q=xxxx Search input (URL/UTF-8 encoded). Case insensitive.
limit=123 Upper limit for the number of items to be returned.
cat=xxx List of categories to search delimited by ","
o=xxx Output format, either "JSON" or "XML". Default is "XML".
extended=1 Return extended information in the search results. (See DETAILS).
del=1 Delete the item from a users cart on download.
maxage=123 Only return results which were posted to usenet in the last x days.
offset=50 The 0 based query offset defining which part of the response we want.
Examples:
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=a%20tv%20show
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
<channel>
<title>example.com</tile>
<description>example.com API results</description>
<!--
More RSS content
-->
<!-- offset is the current offset of the response total is the total number of items found by the query -->
<newznab:response offset="0" total="2344"/>
<item>
<!-- Standard RSS 2.0 Data -->
<title>A.Tv.Show.S06E05.DVDRIP.XviD</title>
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
<category>TV > XviD</category>
<description>Some TV show</description>
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
<!-- Additional attributes -->
<newznab:attr name="category" value="2000"/>
<newznab:attr name="category" value="2030"/>
<newznab:attr name="size" value="4294967295"/>
</item>
</channel>
</rss>
// no items matched the search criteria
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<rss>
<channel>
<newznab:response offset="0" total="0"/>
</channel>
</rss>
// Query could not be completed because user credentials are broken
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<error code="100" description="Incorrect user credentials"/>
// Query could not be completed because it was malformed
--> GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"/>
<error code="200" description="Missing parameter: key"/>
2.4 TV-SEARCH
Description:
TV-SEARCH function searches the index in the TV category for items matching the search criteria.
The criteria includes query string and in addition information about season and episode.
On successful search the response contains a list of items that matched the query. Even if the
search matched nothing an empty but valid response is created and returned. This function
requires passing the user credentials.
It is important to note, that all parameters are treated as AND operations execept for rid, tvdbid,
traktid, tvmazeid, imdbid, and tmdbid. Supplying any combination (some, none, all) of these values will
return results applicable for each value respective to the other AND parameters.
The returned XML data stream is RSS 2.0 compliant and also contains additional information
in the extra namespace and optionally TV specific information
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=tvsearch TV-Search function, must always be "tvsearch".
apikey=xxx User's key as provided by the service provider.
Optional parameters:
limit=123 Upper limit for the number of items to be returned, e.g. 123.
rid=xxxx TVRage id of the item being queried.
tvdbid=xxxx TVDB id of the item being queried.
traktid=xxxx TraktTV id of the item being queried.
tvmazeid=xxxx TVMaze id of the item being queried.
imdbid=xxxx IMDB id of the item being queried.
tmdbid=xxxx TMDB id of the item being queried.
cat=xxx List of categories to search delimited by ","
season=xxxx Season string, e.g S13 or 13 for the item being queried. Can also be YYYY for Daily Show.
q=xxxx Search input (URL/UTF-8 encoded). Case insensitive.
ep=xxx Episode string, e.g E13 or 13 for the item being queried. Can also be MM/DD for Daily Show.
o=xml Output format, either "JSON" or "XML". Default is "XML".
extended=1 Return extended information in the search results
del=1 Delete the item from a users cart on download.
maxage=123 Only return results which were posted to usenet in the last x days.
offset=50 The 0 based query offset defining which part of the response we want.
Examples:
--> GET http://servername.com/api?t=tvsearch&apikey=xxxq=lost&season=S03
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
<channel>
<title>example.com</title>
<description>example.com API results</description>
<!--
More RSS content
-->
<!-- offset is the current offset of the response
total is the total number of items found by the query
-->
<newznab:response offset="0" total="1234"/>
<item>
<!-- Standard RSS 2.0 data -->
<title>Land.of.the.Lost.S03E02.Survival.Kit.iNTERNAL.DVDRip.XViD-SPRiNTER</title>
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
<category>TV > XviD</category>
<description>Some TV show</description>
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
<!-- Additional attributes -->
<newznab:attr name="category" value="5030"/>
<newznab:attr name="size" value="154653309"/>
<newznab:attr name="season" value="3"/>
<newznab:attr name="episode" value="2"/>
</item>
<item>
<!-- Standard RSS 2.0 data -->
<title>Lost.S03E01.720p.BluRay.DTS.x264.INTERNAL-hV</title>
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
<category>TV > XviD</category>
<description>Some TV show</description>
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
<!-- Additional attributes -->
<newznab:attr name="category" value="5000" />
<newznab:attr name="category" value="5030" />
<newznab:attr name="size" value="4294967295" />
<newznab:attr name="season" value="3"/>
<newznab:attr name="episode" value="1"/>
</item>
<!-- more items to follow -->
</channel>
</rss>
2.5 MOVIE-SEARCH
Description:
MOVIE-SEARCH function searches the index for items matching an IMDB id or search query.
On successful search the response contains a list of items that matched the query. Even if the
search matched nothing an empty but valid response is created and returned. This function
requires passing the user credentials.
The returned XML data stream is RSS 2.0 compliant and also contains additional information
in the extra namespace and optionally movie specific information.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=movie Movie-Search function, must always be "movie".
apikey=xxx User's key as provided by the service provider.
Optional parameters:
limit=123 Upper limit for the number of items to be returned, e.g. 123.
imdbid=xxxx IMDB id of the item being queried e.g. 0058935.
cat=xxx List of categories to search delimited by ","
q=xxxx Search input (URL/UTF-8 encoded). Case insensitive.
o=xml Output format, either "JSON" or "XML". Default is "XML".
extended=1 Return extended information in the search results
del=1 Delete the item from a users cart on download.
maxage=123 Only return results which were posted to usenet in the last x days.
offset=50 The 0 based query offset defining which part of the response we want.
Examples:
--> GET http://servername.com/api?t=movie&apikey=xxx&imdbid=0058935
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
<channel>
<title>example.com</title>
<description>example.com API results</description>
<!--
More RSS content
-->
<!-- offset is the current offset of the response
total is the total number of items found by the query
-->
<newznab:response offset="0" total="1234"/>
<item>
<!-- Standard RSS 2.0 data -->
<title>Movie.Name.720p.BluRay.DTS.x264</title>
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
<category>Movie > XviD</category>
<description>Some movie</description>
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
<!-- Additional attributes -->
<newznab:attr name="category" value="2000" />
<newznab:attr name="category" value="2030" />
<newznab:attr name="size" value="4294967295" />
</item>
</channel>
</rss>
2.6 DETAILS
Description:
DETAILS function returns all information for a particular Usenet (NZB) item. The response
contains the generic RSS part + full extra information + full type/category specific information.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=details Details function, must always be "details".
guid=xxxx The GUID of the item being queried.
apikey=xxxx User's key as provided by the service provider.
Optional parameters:
o=xxx Output format, either "JSON" or "XML". Default is "XML".
del=1 Delete the item from a users cart on download.
Example:
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
<channel>
<item>
<!-- Standard RSS 2.0 Data -->
<title>A.Tv.Show.S06E05.DVDRIP.XviD</title>
<guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid>
<link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9</link>
<comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments>
<pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate>
<category>TV > XviD</category>
<description>Some TV show</description>
<enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" />
<!--
Additional attributes
Details function returns all possible attributes that are 1) known and 2) applicable
for the item requested.
-->
<newznab:attr name="category" value="2000" />
<newznab:attr name="category" value="2030" />
<newznab:attr name="size" value="4294967295" />
<newznab:attr name="files" value="107" />
<newznab:attr name="poster" value="example@4u.net (example)" />
<newznab:attr name="grabs" value="1" />
<newznab:attr name="comments" value="0" />
<newznab:attr name="usenetdate" value="Tue, 22 Jun 2010 06:54:22 +0100" />
<newznab:attr name="group" value="alt.binaries.movies.divx" />
</item>
</channel>
</rss>
// Query could not be completed because it was malformed
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"/>
<error code="200" description="Missing parameter: key"/>
// Query could not be completed because no such item was available
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"/>
<error code="300" description="No such GUID"/>
// Query could not be completed because user credentials are broken
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"/>
<error code="100" description="Incorrect user credentials"/>
2.7 INFO
Description:
INFO function returns the contents of the release info in text format. It can also return the contents as an nfo
file with extra parameters.
HTTP Method:
GET
HTTP Response:
200 OK
Parameters:
t=info Info function. Can be info, nfo, or n.
guid=xxxx The GUID of the item being queried.
apikey=xxxx User's key as provided by the service provider.
Optional parameters:
o=xxx Output format, can be "file" or "text". Default is "text".
Example:
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
<-- 200 OK
<-- Contents of NFO blob with nl2br OR octet-stream of NFO blob
// Query could not be completed because it was malformed
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"/>
<error code="200" description="Missing parameter: key"/>
// Query could not be completed because no such item was available
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"/>
<error code="300" description="No such GUID"/>
// Query could not be completed because user credentials are broken
--> GET http://servername.com/api?t=info&r=xxxxx&id=xxxxxxxxx
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"/>
<error code="100" description="Incorrect user credentials"/>
3. Predefined Categories
In order to facilitate operation that does not rely on a particular natural language, e.g. english
a set of predefined category IDs have been defined. It is possible to define custom categories
in the custom category range. Each category is given a range for a set of subcategories. It is possible
for an item to belong to several categories at the same time.
Category Range Category Name Comments
0000-0999 Other
1000-1999 Console
2000-2999 Movies
3000-3999 Audio
4000-4999 PC
5000-5999 TV
6000-6999 XXX
7000-7999 Books
8000-99999 Reserved Reserved for future expansion
100000- Custom Site specific category range. Defined in CAPS
Categories Category Name
0000 Other All of Other
0010 Other/Misc Anything that could not get categorized
0020 Other/Hashed Anything with a hashed name
1000 Console All of console
1010 Console/NDS Nintendo DS
1020 Console/PSP Sony Playstation Portable
1030 Console/Wii Nintendo Wii
1040 Console/Xbox Microsoft XBox
1050 Console/Xbox 360 Microsoft XBox 360
1060 Console/Wiiware/VC Wii homebrew
1070 Console/XBOX 360 DLC Microsoft XBox 360 Downloadable Content
1080 Console/PS3 Playstation 3
1999 Console/Other Misc Console
1110 Console/3DS Nintendo 3DS
1120 Console/PS Vita Playstation Vita
1130 Console/WiiU Nintento Wii U
1140 Console/Xbox One Xbox One
1180 Console/PS4 Playstation 4
2000 Movies All of movies
2010 Movies/Foreign Non english movies
2020 Movies/Other Misc movies
2030 Movies/SD Standard definition movies
2040 Movies/HD High definition movies (720p+)
2050 Movies/3D 3D movies
2060 Movies/BluRay Full BR movies
2070 Movies/DVD Full DVD movies
2080 Movies/WEBDL WEB-DL movies
3000 Audio All of audio
3010 Audio/MP3 Mp3 music
3020 Audio/Video Music videos
3030 Audio/Audiobook Books in audio format
3040 Audio/Lossless Lossless music
3999 Audio/Other Misc music
3060 Audio/Foreign Non english music.
4000 PC All of PC
4010 PC/0day Apps and games not released in ISO.
4020 PC/ISO CD-ROM images/DVD Images
4030 PC/Mac OS X apps and games
4040 PC/Phone-Other Misc mobile phone software
4050 PC/Games PC Games
4060 PC/Phone-IOS IOS apps
4070 PC/Phone-Android Android apps
5000 TV All of TV
5010 TV/WEB-DL WEB-DL TV
5020 TV/FOREIGN FOREIGN TV
5030 TV/SD SD TV
5040 TV/HD HD TV
5999 TV/OTHER Other TV Content
5060 TV/Sport Sports
5070 TV/Anime Anime
5080 TV/Documentary Documentaries
6000 XXX All of XXX
6010 XXX/DVD Full DVD's
6020 XXX/WMV WMV rips
6030 XXX/XviD dvdrips
6040 XXX/x264 HD Porn
6999 XXX/Other Misc Porn
6060 XXX/Imageset Sets of porn images
6070 XXX/Packs Packs of multiple porn videos
7000 Books All of Books
7010 Books/Magazines Magazines
7020 Books/Ebook Ebooks
7030 Books/Comics Comics Ebooks
7040 Books/Technical Technical books
7060 Books/Foreign Non english books
7999 Books/Unknown Misc books
100000+ Custom Specific to a site
4. PREDEFINED ATTRIBUTES
A set of known attributes for items in different categories has been defined.
Its possible that not all attributes are available at all times. Therefore a
client application should not rely on any particular attributes being in the
returned data but should take this list as an optional extra information.
However attributes marked with * are always available.
Additionally, not all attributes are applicable to all items. The category
information can be used to check which attributes area available for which
category items.
All attributes are defined using XML namespace syntax.
e.g. xmlns:newznab="http://www.newznab.com/DTD/2010/feeds/attributes/"
4.1 List of Attributes
Attribute Category Description Example value
size * ALL Size in bytes "252322"
category * ALL Item's category "5004"
files ALL Number of files "4"
poster ALL NNTP Poster "yenc@power-post"
group ALL NNTP Group(s) "a.b.warez, a.b.teevee"
team ALL Team doing the release "DiAMOND"
grabs ALL Number of times item downloaded "1"
password ALL Whether the archive is passworded "0" no, "1" rar pass, "2" contains inner archive
comments ALL Number of comments "2"
usenetdate ALL Date posted to usenet "Tue, 22 Jun 2010 06:54:22 +0100"
info ALL Info (.nfo) file URL "http://somesite/api?t=info&id=xxx"
year ALL Release year "2009"
prematch ALL Has valid PreDB match "0" no "1" yes
season TV Numeric season "1"
episode TV Numeric episode within the season "1"
videos_id TV, Movies, Anime Local Video ID "1"
tv_episodes_id TV Local TV Episode ID "1"
tvdbid TV TVDB ID. (www.thetvdb.com) "153021"
traktid TV TraktTV ID. (www.trakt.tv) "1393"
rageid TV TVRage ID. (www.tvrage.com) "25056"
tvrageid TV TVRage ID. (www.tvrage.com) "25056"
tvmazeid TV TVMaze ID. (www.tvmaze.com) "73"
imdbid TV IMDB ID for show. (www.imdb.com) "tt1520211"
tmdbid TV TMDB ID for show. (www.themoviedb.com) "1402"
title TV TV Show Title. (www.tvrage.com) "Duck and Cover"
firstaired TV TV Show Air date. (www.tvrage.com) "Tue, 22 Jun 2010 06:54:22 +0100"
anidbid Anime AniDB.net ID. (www.anidb.net) "10445"
video TV, Movies Video codec "x264"
audio TV, Movies, Audio Audio codec "AC3 2.0 @ 384 kbs"
resolution TV, Movies Video resolution "1280x716 1.78:1"
framerate TV, Movies Video fps "23.976 fps"
language TV, Movies, Audio Natural languages "English"
subs TV, Movies Subtitles "English, Spanish"
imdb TV, Movies IMDb ID (www.imdb.com) "0104409"
genre TV, Movies Genre "Horror"
4.2 Attribute Example
Example attribute declarations within <item> element.
<newznab:attr name="category" value="2000" />
<newznab:attr name="category" value="2030" />
<newznab:attr name="size" value="4294967295" />
5. nZEDb Error Codes
Under normal circumstances i.e. when the HTTP request/response sequence is successfully completed
nZEDb implementations always respond with HTTP 200 OK. However this does not mean that the
query was semantically correct. It simply means that the HTTP part of the sequence was successful.
One then must check the actual response body/data to see if the request was completed
without errors.
In case of a nZEDb error the response contains an error code and an a description of the error.
The error codes have been defined into different ranges. 100-199 Account/user credentials specific
error codes, 200-299 API call specific error codes, 300-399 content specific error codes and finally
900-999 Other error codes.
Error code Description
100 Incorrect user credentials
101 Account suspended
102 Insufficient privileges/not authorised
103 Registration denied
104 Registrations are closed
105 Invalid registration (Email Address Taken)
106 Invalid registration (Email Address Bad Format)
107 Registration Failed (Data error)
200 Missing parameter
201 Incorrect parameter
202 No such function. (Function not defined in this specification).
203 Function not available. (Optional function is not implemented).
300 No such item.
500 Request limit reached
501 Download limit reached
900 Unknown error
5.1 Error code example
// Query could not be completed because user credentials are broken
--> GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx
<-- 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<error code="100" description="Incorrect user credentials"/>
6 Changelog
2015-10-24 ruhllatio
Add new attribute returns.
Update supported tv-search methods.
Add audio-search capability and make it unavailable with no params.
2015-05-23 kevinlekiller
Fix spelling issues.
Fix indentation issues.
Add missing categories.
Add missing error codes.