Search API Documentation

Here you will find detailed documentation on the request and response formats for Thumbplay's search API. Please note that you must have an activated pname in order to make requests. Your pname acts as both your partner ID for reporting and API key for authentication.

1.0 Request Format

If you are submitting the request programmatically, please be sure to URL-encode the parameters.

1.1 Example URL Pattern

http://api.hosted.thumbplay.com/api/rest/search/content?keywords=kanye%20stronger&contentTypes=Music%20ringtone&pname=1003&plpFlow=artisttitle

1.2 Parameters

Name Expected Value Example Description
keywords space separated words keywords=kanye stronger Search will be performed with fuzzy matching across the given keywords associated with logical AND
contentTypes Pipe (“|”) separated values, One of: Music ringtone, Ringtone, Wallpaper, Animation, Game, Video contentTypes=Ringtone|Video Search will be constrained to the given content types
title Space separated words title=stronger Search will be constrained to the given title (not fuzzy)
artist Space separated words artist=kanye west Search will be constrained to the given artist (not fuzzy)
startIndex Non-negative integer startIndex=5 The index of the first search result to be returned, with respect to all of the results found. Min value is 0. If missing or negative, the value is interpreted to be 0.
maxReturnedResults Non-negative integer maxReturnedResults=10 The number of search results to return. Min value is 0. If missing, the value is interpreted to be MAX_INT. If negative, the value is interpreted to be 0.
pname Non-negative integer pname=1003 Partner ID and API key used for reporting and authentication. Will be appended to the URLs returned within the search results
ptrx Word or non-negative integer ptrx=video_player Secondary tracking ID useful for tracking of partner placements. Not required for reporting or authentication.
plpFlow for now, the only valid value is "artisttitle" plpFlow=artisttitle Artist Specific Partner Landing Page URL and Title Specific Partner Landing Page URL will be generated with the given value. If no value is specified or if the value is recognized as a valid flow, the Artist Landing Page URL and Title Landing Page URL will be generated using the value “artisttitle. ” No Artist Landing Page URL and Title Landing Page URL will be generated if the pname parameter is not provided.

2.0 Response Format

2.1 Sample - Successful Response

<contentResults>
   <contentResult>
       <albumName>Stronger</albumName>
       <artist>Kanye West</artist>
       <artistId>130828</artistId>
       <artistLandingPageURL>
          http://offers.thumbplay.com/offers/1003/artisttitle?thpartist=Kanye+West
       </artistLandingPageURL>
       <artistURL>
          http://ringtones.thumbplay.com/Kanye+West-ringtones
       </artistURL>
       <contentId>519626</contentId>
       <contentType>Music ringtone</contentType>
       <imageLargeURL>
          http://www.thumbplay.com/images/content/no-image-lg-realtone.gif
       </imageLargeURL>
       <imageMediumURL>
          http://www.m-kube.com/msmartclient/images/user-covers/img_519626_1_170.jpg
       </imageMediumURL>
       <imageSmallURL>
          http://www.m-kube.com/msmartclient/images/user-covers/img_519626_1_75.jpg
       </imageSmallURL>
       <mobilePurchaseURL>
          http://m.thumbplay.com/tp/infomo?view=details2&cid=519626&pname=1003
       </mobilePurchaseURL>
       <previewURL>
          http://preview.thumbplay.com/VAN/Thumb_Preview/Real/UMG/Kanye_West.Stronger-00602517415850-19.85.mp3
       </previewURL>
       <score>1.0</score>
       <title>Stronger</title>
       <titleLandingPageURL>
          http://offers.thumbplay.com/offers/1003/artisttitle?thpartist=Kanye+West&thptitle=Stronger
       </titleLandingPageURL>
       <webPurchaseURL>
          http://www.thumbplay.com/join/Kanye+West-artist-Stronger-realtones-bonus?pname=1003
       </webPurchaseURL>
   </contentResult>
</contentResults>
<queryDuration>107</queryDuration>
<searchRequest>
   <contentTypes>Music ringtone</contentTypes>
   <keywords>kanye stronger</keywords>
   <plpFlow>artisttitle</plpFlow>
   <pname>1003</pname>
</searchRequest>
<totalResultCount>1</totalResultCount>

2.2 Field Description

Name Description
albumName Name of the album
artist Name of the artist
artistID Unique identifier for the artist
artistLandingPageURL URL for the best-converting artist-specific partner landing page (recommended)
artistURL URL for the artist page on Thumbplay main site (not recommended)
contentID Unique identifier for the content item
contentType Type of the content item. One of: Music ringtone, Ringtone, Wallpaper, Animation, Game, Video
imageLargeURL URL for the large version of the thumbnail image for the content
imageMediumURL URL for the medium version of the thumbnail image for the content
imageSmallURL URL for the small version of the thumbnail image for the content
mobilePurchaseURL URL for the purchase page for the content - suitable for WAP viewing
previewURL URL for the preview version of the content
score The rating from the search engine. A floating point number from 0 to 1.0, inclusive, with 1.0 being the highest.
title Title of the content item
titleLandingPageURL URL for the best-converting title-specific partner landing page (recommended)
webPurchaseURL URL for the title page on Thumbplay main site (not recommended)

2.3 Sample - Response With Errors

<errors>
  <error>
    <code>1</code>
    <description>Unknown content type abcdef</description>
  </error>
</errors>
<queryDuration>1</queryDuration>
<searchRequest>
  <contentTypes>abcdef</contentTypes>
  <keywords>kanye stronger</keywords>
  <plpFlow>artisttitle</plpFlow>
  <pname>1003</pname>
</searchRequest>

2.4 Field Description

Name Description
code Possible values: 0 - Error code undefined, 1 - Bad content type value, 2 - Missing search criteria, 3 - Service unavailable
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.