Browse Collections Artists Sources   Find Search

Add Show Source    |    List Management    Forums    Help


Welcome to db.etree.org's REST interface

This service is provided for individuals and web sites wishing to query db's content. This is a free service but requires a service key to use. To request a service key email db@etree.org. Be sure to include your sites name, your username, and the amount of daily traffic you expect to have with db.

There is a db REST mailing list you will be invited to join once you receive your service key. Membership is mandatory. This list will be primarily used to announce api changes, discuss REST implementations, and request new features.

The REST url is http://db.etree.org/rest/db.php
Some bt.etree.org data is available through REST too. See the bt.etree.org section below.

Data Retrieval Interfaces

fetchArtist ( $service_key, $artist_key); Returns an array with the artist key and name for the given artist.

fetchShow ( $service_key, $shows_key); Returns a single show entry. You must provide the shows_key, aka showid, for the exact show you want.

lookupShow ( $service_key, $artist_key, $year, $month, $day) Returns an array of shows matching the artist_key, year, month, and day. Some artists have more than one show per day. This method will always return an array of shows. A maximum of 25 shows will be returned.

lookupArtist ($service_key, $name) Returns an array of matching artist names. You may include % wildcards. This method will return a maximum of 25 artist names.

lookupMd5 ($service_key, $md5) Returns an array of source keys with a matching md5. Your md5 must be 32 characters long exactly. Will always return an array of source keys even though most queries will only have one result.

fetchArtistYear ($service_key, $artist_key, $year) Returns an array of show information for all shows by the selected artist in the given year.

fetchSource ($service_key, $source_key) Returns a single source record for the given source_key, aka shnid.

fetchSourceYear ($service_key, $artist_key, $year) Returns an array of sources for the selected artist for the given year.

fetchChangedShows ($service_key, $artist_key, $year, $month, $day) Returns an array of shows_keys which have been changed since the given date. Use artist_key=0 to fetch all shows.

fetchChangedSources ($service_key, $artist_key, $year, $month, $day) Returns an array of source keys which have been changed since the given date. Use artist_key=0 to fetch all sources.

fetchChangedArtists ($service_key, $year, $month, $day) Returns an array of artist_keys which have been changed since the given date.

fetchShowSources ($service_key, $shows_key) Returns an array of source keys for the given show.

Data Update Interfaces

updateSource($service_key, $source_key, $field, $value) Updates the given source id with the field value. Valid fields are archive_identifier, textdoc,media_size, and comments. You must be a source admin to update your sources. This will also update the last edited user field and the last update date. Changes are audited but changes are not put through the peer review process.

createMd5 ($service_key, $source_key, $title, $text) Create a new md5 record for the given source key. Returns the new md5 key. You must be a source admin to add md5s to a source.

deleteMd5 ($service_key, $md5_key) Delete an md5 record from a source. You must provide the md5 key which is available through the fetchSource method. You must be a source admin to delete md5s from a source.

bt.etree.org REST interface

This service is provided through db on the behalf of bt.etree.org (bt.e). bt.e has placed restrictions on the use of this data. You may not provide a direct link to download a torrent. You may use this data as you see fit but you must direct users to the official details page (http://bt.etree.org/details.php?id=# where # is the torrent id) to start a download.

Next, an understanding of the relationship between bt.e and db is required. The two databases share a common user login table and that is all. The fields which make it possible to query these resources together are ref_dbshn and ref_dbshow in the torrents table. These fields are manually populated by bt.e users when they create a torrent. They may be manually updated through db.etree's tie-in script at http://db.etree.org/shnmaint/bt.etree.php but you must be a source volunteer at db to access this page.

These two fields allow me to query bt.e's database and tie it to db's tables so I can find all torrents belonging to a particular artist or show. Because the ref_dbshn may be populated when ref_dbshow is not this is taken into concideration when querying the tables and a double outer join between torrents and shows and shninfo is created. While this is probably too complicated an explaination I hope it shows the weakness in the system: If a torrent doensn't have it's db source or show data it will not show up in this REST interface.

The REST url for the bt.e interface is http://db.etree.org/rest/bt.php

Data Retrieval Interfaces

fetchShowTorrents($service_key, $shows_key); Return details for all torrents for the given show.

fetchRecentTorrents($service_key, $artist_key, $year, $month, $day, $limit); Return details for all torrents since $year-$month-$day for the optional artist (use $artist_key = 0 for all) limited to the last $limit torrents. $limit is capped at 50.