Retrieving Data from tagChimp
Introduction
The interface to the data provided by tagChimp is very easy to use in your application. Data is retrieved by sending a simple query via the HTTP GET protocol. tagChimp will respond to the query with a clean, concise XML document containing the lookup or search results. This XML can easily be parsed to extract the data that you need.
The Search Query
Letʼs start by taking a look at forming the query. Queries can either be in the form of a search or a lookup. A search will give several results that closely match the search term that you send. A lookup will yield one result, and only if an exact match occurs.
Search Query
https://www.tagchimp.com/ape/search.php?token=YourToken&type=search&title=SearchTerm
&totalChapters=#ofChapters&limit=NumberToShow&locked=IsLocked
Lookup Query
https://www.tagchimp.com/ape/search.php?token=YourToken&type=lookup&title=SearchTerm
&totalChapters=#ofChapters
The Components of the Query
| Required Fields | |
| token | This is your developer token that you received from tagChimp at registration. (Note: This is not your secret key. The secret key is used for uploading/POSTing data only.) example: &token=ABCDEFGHIJKLMNOP1234567 |
| type | The flag which determines whether the query is a search or lookup. example: &type=search |
| title | This is the main search term: the title of your movie, TV show episode (NOT the name of the TV show!) or music video. example: &title=Horton+Hears+A+Who! |
| totalChapters | Integer. The total number of chapters contained in the video file. This is used as a "fingerprint" to help identify matches while searching or performing a lookup. Send a 0 if no chapters exist, or an X to return everything regardless of chapter count. examples: |
| Optional Fields | |
| id | For an exact result you can enter the ID number of the title you wish to retrieve. example: &id=63967 |
| lang | You can append a 2-character language code to only search for titles in a particular language. See a list of supported languages. example: &lang=en |
| uid | Enter the user's ID for more personalized results. examples: |
| limit | You can limit the number of search results. For instance, if you only want to see the first five results you would enter 5. example: &limit=5 |
| locked | Only show locked titles. Titles that are locked are considered to be of the highest quality. example: &locked=true |
| amazon | The Amazon ASIN number if you know it example: &amazon=B001DTUTU8 |
| imdb | The unique IMDB ID number. example: &imdb=0451079 |
| netflix | The unique Netflix ID number. example: &netflix=70077554 |
| gtin | The unique discIdent GTIN (see www.discident.com for more info) example: >in=00254129856325 |
| show | The name of the television show example: &show=House |
| season | The season number of the television show example: &season=1 |
| episode | The episode number of the television show example: &episode=10 |
| videoKind | Further filter the results based upon the video file type. Options are Movie, TVShow and MusicVideo. Note: if 'show' is present in the query, you don't need to include videoKind as tagChimp will already assume it's a TV show. example: &videoKind=Movie |
Let's see a Movie query.https://www.tagchimp.com/ape/search.php?token=123&type=search&title=Horton+Hears+A+Who! Let's see a TV show queryhttps://www.tagchimp.com/ape/search.php?token=123&type=search&show=House&season=1&episode=10 Of course, you don't need all of these fields. If you're looking up a title and are using the tagChimp ID, you don't need to use the Amazon ASIN, IMDB ID, Netflix ID or the videoKind, as that's overkill. Same goes for using the netflixID, etc.. If you're looking up TV shows, try it this way Note: Looking up the Amazon ASIN, IMDB ID, Netflix ID or GTIN will be hit or miss as not all tagChimp records will contain them. Yet. |
|
Retrieving Results in XML
This is what a tagChimp XML result will look like. tagChimp uses CaMeL CaSinG. Make sure your element names are CaSe CorrEcT!. Depending upon the movie, you may see different release date formats. tagChimp didn't force the release dates to be in a certain format in the beginning. Now we do: YYYY-MM-DD. Depending upon when the movie was added will depend upon which release date fields are populated. You should plan your logic accordingly.
<?xml version="1.0" encoding="utf-8" ?>
<items>
<totalResults></totalResults>
<movie>
<locked></locked>
<language></language>
<tagChimpID></tagChimpID>
<amazonASIN></amazonASIN>
<imdbID></imdbID>
<netflixID></netflixID>
<iTunesURL></iTunesURL>
<gtin></gtin>
<movieTags>
<info>
<kind></kind>
<title></title>
<releaseDate></releaseDate> (depreciated)
<releaseDateY></releaseDateY>
<releaseDateM></releaseDateM>
<releaseDateD></releaseDateD>
<genre></genre>
<additionalGenres>
<genre></genre>
</additionalGenres>
<rating></rating>
<directors>
<director></director>
</directors>
<producers>
<producer></producer>
</producers>
<screenwriters>
<screenwriter></screenwriter>
</screenwriters>
<cast>
<actor></actor>
</cast>
<shortDescription></shortDescription>
<longDescription></longDescription>
<advisory></advisory>
<copyright></copyright>
<comments></comments>
</info>
<television>
<seasonLocked></seasonLocked>
<showName></showName>
<season></season>
<episode></episode>
<episodeID></episodeID>
<productionCode></productionCode>
<network></network>
</television>
<sorting>
<name></name>
<artist>
<artistName></artistName>
</artist>
<albumArtist></albumArtist>
<album></album>
<show></show>
</sorting>
<track>
<trackNum></trackNum>
<trackTotal></trackTotal>
</track>
<coverArtLarge></coverArtLarge>
<coverArtSmall></coverArtSmall>
<movieChapters>
<totalChapters></totalChapters>
<chapter>
<chapterNumber></chapterNumber>
<chapterTitle></chapterTitle>
<chapterTime></chapterTime>
</chapter>
</movieChapters>
</movie>
</items>
Note: locked will return 'yes' if the title is locked, 'no' if not. episode is an integer and will return 0 if empty. Code your results accordingly.
Summary
The interface to retrieve data from tagChimp is very easy to use, and can be done in virtually any programming language that you desire. Sign up for your developer account today!
 
|
|||||||||||||
| © 2010 tagChimp | | | home | | | sign up | | | contact | | | created by Tim Gavin | | | hosted by G Interactive | | | grab my feed |  |
