Charts API Documentation
Here you'll find documentation on the request and response formats for Thumbplay’s Top 10 Charts and New Content API. This REST API provides a simple way for you to get our most popular and newest ringtones, games and graphics. We update these APIs weekly, so you'll be sure to have the hottest, most up-to-date content available. Keep in mind that you'll need to include your Partner ID when making requests. Important: we assume you'll be making programmatic API calls. After retrieving the contentIds from the API below, you can make one call to the Links API to get the best landing page for each piece of content. As always, we love it when partners send us feedback.
1.0 Request Format
If you are submitting the request programmatically, please be sure to URL-encode the parameters.
1.1 GetContent URL Pattern
http://api.hosted.thumbplay.com/api/rest/catalog/contentItem?moduleCode=ringtone-chart&clientRequestId=myRequest01&pname=1003
1.2 Parameters
| Name | Expected Value | Example | Description |
|---|---|---|---|
| moduleCode | predefined module code, please see 1.3 moduleCode Values below | moduleCode=ringtone-chart | This ID is specific to a set of predefined contentCodes, and requests all content specific to that moduleCode |
| clientRequestId | partner-defined values, not required | clientRequestId=myRequest01 | Although this variable is not required, Thumbplay will include this partner-defined value in the XML response logging purposes |
| pname | Non-negative integer | pname=1003 | This is your unique Partner ID that is assigned to you when you register. This ID allows us to provide reporting and authenticate your API calls. |
1.3 moduleCode Values
| Code | Description |
|---|---|
| ringtone-chart | returns the Top 10 ringtone chart |
| graphic-chart | returns the Top 10 graphics chart |
| game-chart | returns the Top 10 game chart |
| new-realtone | returns the newest real music tones |
| new-wallpaper | returns the newest graphics |
| new-game | returns the newest mobile games |
2.0 Response Format
2.1 Sample - Successful Response
<contentItemResponse>
<duration>10</duration>
<contentItemRequest>
<moduleCode>new-ringtone</moduleCode>
<categoryId>101</categoryId> <!-- If category identifier is not specified then will be empty -->
<clientRequestId>myRequest01</clientRequestId>
</contentItemRequest>
<contentItem>
<contentFullInfo>
<contentId>
<id>477738</id>
</contentId>
<contentType>
<id>6</id>
<name>Music ringtone</name>
</contentType>
<name>Wolf Like Me</name>
<description>Description</description>
<artistShortInfo>
<artistId>
<id>264430<id>
</artistId>
<name> TV On The Radio </name>
<image> http://preview.thumbplay.com/www/thumbplay.com/images/bio/tv_on_the_radio_bio_120x120.jpg </image>
</artistShortInfo>
<albumShortInfo>
<albumId>
<id>936017</id>
</albumId>
<name>Return To My Cookie Mountain</name>
<imageSmall>http://images.m-kube.com/muzecovers/75/936017.jpg</imageSmall>
<imageMedium>http://images.m-kube.com/muzecovers/170/936017.jpg</imageMedium>
<imageLarge>http://images.m-kube.com/muzecovers/450/936017.jpg</imageLarge>
</albumShortInfo>
<previewPath>http://images.m-kube.com/muzecovers/75/936017.jpg</previewPath>
<imageSmall>http://images.m-kube.com/muzecovers/75/936017.jpg</imageSmall>
<imageMedium>http://images.m-kube.com/muzecovers/170/936017.jpg</imageMedium>
<imageLarge>http://images.m-kube.com/muzecovers/450/936017.jpg</imageLarge>
<imageStill>http://images.m-kube.com/muzecovers/450/936017.jpg</imageStill>
</contentFullInfo>
</contentItem>
</contentItemResponse>
2.2 Successful Response - Field Description
| Name | Description |
|---|---|
| duration | Time duration of method execution |
| description | Printable description of the error |
| contentId/id | Content identifier. |
| contentType/id | Identifier of content type. |
| contentType/name | Name of content type. |
| name | Content name. |
| description | Content description. |
| artistShortInfo/artistId/id | Artist identifier. |
| artistShortInfo/name | Artist name. |
| artistShortInfo/image | Image path for artist. |
| albumShortInfo/albumId/id | Album identifier. |
| albumShortInfo/name | Album name. |
| albumShortInfo/imageSmall | Small image of album. |
| albumShortInfo/imageMedium | Medium image of album. |
| albumShortInfo/imageLarge | Large image of album. |
| previewPath | Content preview path. |
| imageSmall | Content small image |
| imageMedium | Content medium image |
| imageLarge | Content large image |
| imageStill | Still image of content. |
2.3 Sample - Response With Errors
<contentItemResponse>
<duration>10</duration>
<contentItemRequest>
<moduleCode>ringtone-chart</moduleCode>
<categoryId>101</categoryId>
<clientRequestId>myRequest01</clientRequestId>
</contentItemRequest>
<errors>
<error>
<description>Unknown category identifier.</description>
<code>102</code>
<debugInfo></debugInfo>
</error>
2.4 Response with Errors - Field Description
| Name | Description |
|---|---|
| code | 101 - 300 is not success (error) codes. Possible values: 121 – Unknown module code. 122 – Module code or category identifier should be specified at least. 112 – Unknown category identifier. 200 – A communication error has occurred. 201 – Generic error. |
| debugInfo | Debugging information associated with the error. Generated in cases when there have been internal service problems. Should sent to Thumbplay with the bug report. |