Sending Tag Data to tagChimp
Introduction
Interfacing with the database behind tagChimp.com is very simple. The process involves three easy steps:
- Check the database to see if the record exists already
- Upload any image data using HTTP POST
- Upload the record data using HTTP POST
The following document explains these steps in detail.
Check the Database
Before sending data to tagChimp you must first find out if the database already contains the record you are about to send. This is done using the lookup API. Refer to the Search and Retrieve Titles from tagChimp developer guide for creating a lookup query.
If the tagChimp database already contains the record, the resulting XML will include a value for the movieID.
<?xml version="1.0" encoding="utf-8" ?>
<items>
<movie>
<tagChimpID><tagChimpID>
</movie>
Sending this movieID in your POST query will notify tagChimp that it is updating a record*. If no movieID exists in your POST, tagChimp will insert a new record.
Upload image data
If you have image data that you would like to share with tagChimp, send it in an HTTP POST request. The POST must contain the following items:
URL: https://www.tagchimp.com/ape/post.php.This is the URL for the image POST.
key: This is your developer "secret" key that was sent to you at registration
coverArt: The file name for the image you are about to upload
Finally, the image data itself should be appended to the POST.
The file name that you use for the coverArt portion of the POST must conform to some simple guidelines. It should be formed out of the title of the movie, with all punctuation removed and spaces converted to underscores. Append the current date and time and file extension. The final name should follow the format:
rambo_III_20080412164515.jpg
(title_YYYYMMDDHHMMSS.jpg)
Television shows within the same season will all use the same cover art image. The name of this image includes the season number instead of a date-time stamp. For example:
heroes_season_1.jpg
(title_season_seasonNumber.jpg)
You will use this file name as both the coverArtLarge and coverArtSmall portions of the tag POST, described later in this guide. The image data that you include in your POST must be jpeg format and no larger than 1200 pixels tall and 1200 pixels wide. The recommended quality level is 70%-80%.
Upload record data
Sending the textual tag data is very similar to the lookup procedure. Create an HTTP POST with the following constituents:
| POST URL | https://www.tagchimp.com/ape/post.php | |
| key | Your secret key received at registration | |
| tagChimpID | Retrieved from your lookup if the movie already exists in the database | integer |
| lang | The title's language (view supported languages) | char(2) |
| kind | The video kind (Movie, TV Show, Music Video) | text(11) |
| title | The title of the movie, television show episode or music video song name | text(255) |
| amazonASIN | The Amazon.com ASIN for the movie | text(32) |
| imdbID | The Inetenet Movie Database ID | int(7) |
| netflixID | The Netflix ID | int(8) |
| iTunesURL | The direct URL to this title in the iTunes music store | |
| gtin | The item's 14 character discIdent code number (UPC-A or EAN). See www.discident.com for more info | |
| releaseDateY | The release date year (4 digit integer - YYYY) | int(4) |
| releaseDateM | The release date month (2 digit integer - MM) | int(2) |
| releaseDateD | The release date day (2 digit integer - DD) | int(2) |
| category | The genre for the movie (see tagChimp's categories as of 01-2008) | text(32) |
| rating | The MPAA rating for the movie. Sent as human-readable R, PG, PG-13, etc. | text(10) |
| director | A comma separated list of the directors | text(255) |
| producer | A comma separated list of the producers | text(255) |
| screenwriter | A comma separated list of the writers | text(255) |
| cast | A comma separated list of the actors | text |
| shortDescription | The short description shown in the iTunes listing | text(256) |
| longDescription | The long description shown in the iTunes "i" popup window | text |
| showName | The name of the TV series | text(60) |
| season | The season number | int(4) |
| episode | The episode number | int(3) |
| episodeID | The unique ID string for the episode, normally created using the season number and episode number. Season 1 episode 5 would be: 105 | text(32) |
| Production Code | The studio's production code number: T85EDF8 | text(10) |
| tvNetwork | The TV network name that carried the show | text(32) |
| sortName | The title used to sort by in iTunes | text(255) |
| sortArtist | The artist name used to sort by in iTunes | text |
| sortAlbumArtist | The album artist name used to sort by in iTunes | text(255) |
| sortAlbum | The album name used to sort by in iTunes | text(255) |
| sortShow | The TV series name used to sort by in iTunes | text(255) |
| advisory | The content advisory (clean, explicit, none/clear) | text(32) |
| copyright | Any copyright information | text(255) |
| comments | Comments on the movie | text |
| trackNum | The track number | int(4) |
| trackTotal | The total number of tracks | int(4) |
| coverArtSmall | The file name for the cover art | text(255) |
| coverArtLarge | The file name for the cover art | text(255) |
| chapterTitle[] | Movie or TV show chapter title. The chapter number should be placed between the square brackets, while the title of the chapter is the value of this item | text(255) |
| chapterHH[] | Movie or TV show chapter time in hours. The chapter number should be placed between the square brackets, while the hour of the chapter is the value of this item | int(2) |
| chapterMM[] | Movie or TV show chapter time in minutes. The chapter number should be placed between the square brackets, while the minutes of the chapter is the value of this item | int(2) |
| chapterSS[] | Movie or TV show chapter time in seconds. The chapter number should be placed between the square brackets, while the seconds of the chapter is the value of this item | int(2) |
| chapterMS[] | Movie or TV show chapter time in milliseconds. The chapter number should be placed between the square brackets, while the milliseconds of the chapter is the value of this item | int(2) |
All textual items sent via this POST method must be encoded using UTF-8 encoding. Normal escaping should also be done. All integers must be posted as integers or you will receive an error and the entry will be rejected.
Required fields
The following fields are required for any POST to tagChimp.
| key | your secret key (or token if using the sandbox) |
| uid | The user's ID number OR username |
| title | Title of the movie, TV show or music video |
| kind | What kind of video file (Movie, TV Show, Music Video) |
| releaseDateY | Release date year. Try to get month and day if you can! |
| chapterTitle[] | If sending a movie, chapterTitle is required and should not be empty, or named 'Chapter 1', 'Chapter 2', etc. or they will be rejected |
Notice: Starting March 1, 2009, if the following fields are empty, the submission will be rejected.
Movies
kind, title, releaseDateY, rating, directors, cast, shortDescription, longDescription, coverArtLarge, coverArtSmall, totalChapters, chapterNumber, chapterTitle
TV Shows
kind, title, releaseDateY, rating, cast, shortDescription, longDescription, showName, season, episode, espsodeID, network, coverArtLarge, coverArtSmall
Music Videos
kind, title, releaseDateY, name, artist, albumArtist, album, coverArtLarge, coverArtSmall
Summary
tagChimp is a collective effort between developers and users. Being connected to a dynamic data source is very exciting for all involved. Following the guidelines set forth above will help ensure that this experience is the best that it can be for everyone. If you have any questions on the API, come on over and ask them on the tagChimp forums.
 
|
|||||||||||||
| © 2010 tagChimp | | | home | | | sign up | | | contact | | | created by Tim Gavin | | | hosted by G Interactive | | | grab my feed |  |
