mn open: api implementation guide

MediaNet Digital Confidential of 126

MN Open: API Implementation Guide November 2009

Table of Contents MN Open: API Implementation Guide ........................................................................................................... 1 Introduction ................................................................................................................................................. 4

Security: Customer Authentication and Encryption ............................................................................... 5 Transaction Options ............................................................................................................................... 5 Credit Card Payments............................................................................................................................ 5 Account Balance Payments ................................................................................................................... 6 Pricing, Required Retail Price and Tax Handling .................................................................................. 6 Territory Restriction ................................................................................................................................ 7 Album / Track revocation ....................................................................................................................... 7 Bitrate information .................................................................................................................................. 7 MN Open API Best Practices Checklist ................................................................................................. 9 MN Open API Metadata ....................................................................................................................... 10

The MN Open APIs .................................................................................................................................... 11 MN Open API Package and Method Overview ................................................................................... 14 Global Parameters ............................................................................................................................... 16 Paging .................................................................................................................................................. 16 Generating Signatures with your Shared Secret ................................................................................. 16 Tips for Methods That Require a POST Body ..................................................................................... 17 Streaming Samples with Flash: RESOURCE and LOCATION ........................................................... 18 PHP, cUrl, and Content-type Header Setting ...................................................................................... 18 Download Locations and Single Download ......................................................................................... 18 Environments: Integration (IE) and Production (PROD) ...................................................................... 19 How to Search for International Language Data ................................................................................. 19 Handling Album-only Tracks ................................................................................................................ 21 Friendly Filenames ............................................................................................................................... 21 Image Data .......................................................................................................................................... 21 Common Response Data Elements .................................................................................................... 21 Common Errors .................................................................................................................................... 25 Content Discovery ................................................................................................................................ 27

Search.GetTracks ............................................................................................................................ 27 Search.GetAlbums ........................................................................................................................... 28 Search.GetArtists ............................................................................................................................. 29 Search.GetGeoLocation ................................................................................................................... 29 Search.ContentMatch....................................................................................................................... 30 Track.Get .......................................................................................................................................... 31 Track.GetLocations .......................................................................................................................... 31 Album.GetTracks .............................................................................................................................. 32 Artist.GetAlbums .............................................................................................................................. 33 Artist.GetTracks ................................................................................................................................ 34 Label.GetLabelOwner ...................................................................................................................... 33

Provisioning ......................................................................................................................................... 36 User.Create ...................................................................................................................................... 36 User.Get ........................................................................................................................................... 37 User.IsUsernameAvailable ............................................................................................................... 38 User.Login - DEPRECATED ............................................................................................................ 38 User.SetPassword ............................................................................................................................ 39 User.Update ..................................................................................................................................... 40 Cart.AddItems .................................................................................................................................. 41 Cart.Clear ......................................................................................................................................... 43


Cart.Get ............................................................................................................................................ 43 Cart.GetCartByUser ......................................................................................................................... 44 Cart.GetDownloadLocations ............................................................................................................ 44 Cart.Purchase .................................................................................................................................. 45 Cart.RemoveItems ........................................................................................................................... 47 Purchase.UseBalance ...................................................................................................................... 48 Purchase.UseCreditCard ................................................................................................................. 51

Management ........................................................................................................................................ 55 Partner.GetAMGData ....................................................................................................................... 55 Partner.GetBalance .......................................................................................................................... 56 Partner.RefillBalance........................................................................................................................ 56 Report.GetOrderHistory ................................................................................................................... 58

Use Cases .................................................................................................................................................. 59 Typical API calls including request and responses ............................................................................. 60

SEARCH MANAGEMENET USE CASES ....................................................................................... 60 API Calls detailed in this section: ..................................................................................................... 60 Search.GetArtists .................................................................................................................... 60 Search.GetAlbums .................................................................................................................. 60 Search.GetTracks ................................................................................................................... 60 Album.GetTracks..................................................................................................................... 60 Artist.GetAlbums ..................................................................................................................... 60

Search.GetArtists ............................................................................................................................. 61 Search.GetAlbums ........................................................................................................................... 64 Search.GetTracks ............................................................................................................................ 67 Album.GetTracks .............................................................................................................................. 69 Artist.GetAlbums .............................................................................................................................. 71 CART MANAGEMENT USE CASES ............................................................................................... 73 API Calls detailed in this section: ..................................................................................................... 74 Cart.AddItems ......................................................................................................................... 74 Cart.Get ................................................................................................................................... 74 Cart.Purchase ......................................................................................................................... 74 Report.GetOrderHistory .......................................................................................................... 74 Cart.GetDownloadLocations ................................................................................................... 74

Cart.AddItems .................................................................................................................................. 75 Cart.Get ............................................................................................................................................ 76 Cart.Purchase .................................................................................................................................. 77 Cart.GetDownloadLocations ............................................................................................................ 79 Report.GetOrderHistory ................................................................................................................... 80 USER MANAGEMENT USE CASES ............................................................................................... 81 API Calls detailed in this section: ..................................................................................................... 82 User.Create ............................................................................................................................. 82 User.Update ............................................................................................................................ 82

User.Create ...................................................................................................................................... 82 User.Update ............................................................................................................................ 83

Appendix A: Sony Agency Model Nexuses and Tax Rates .................................................................. 84 Appendix B: Label Owners by Identifier and Name .............................................................................. 85 Appendix C: Sample Code ....................................................................................................................... 86

PHP Sample Code of the MNOpen API call to search for an artist’s albums and tracks .................... 86 PHP Sample Code of the MNOpen API call to add a first item to a new cart ..................................... 99 JQuery Sample Code of the MNOpen API call to search for an artist’s albums and tracks .............. 105 IE/JavaScript Sample Code of the MNOpen API call to search for an artist’s albums and tracks .... 108 PHP/jQuery Sample Code of the MNOpen API call to search for an artist’s albums and tracks ...... 111 PERL Sample Code of the MNOpen API call to search for an artist’s albums and tracks ................ 117

Appendix D: Change History / Errata .................................................................................................... 125


Customer Support with the MN Open API To ask questions about and receive support for the MN Open API, please contact [email protected]. This is an internal distribution list monitored by subject matter experts around the company. We will get back to you within 24 hours during regular business hours (Pacific Time).

With any correspondence, please include:

Issue Description including expected and actual results

Repro Steps

API call(s) and response(s) o URL with your query string o POST body content if applicable o Complete response

Please note that in the September revision of this document, we have changed the word “partner” to “customer” in the text to better align this document with our recent marketing campaign changes. Please visit www.mndigital.com for more information. For technical purposes of this API document, the two words are equivalent.

mailto:[email protected]

http://www.mndigital.com/


Introduction

Our MN Open API is an easy to use interface, providing you with rich functionality for music discovery and fulfillment. Technically it is similar to APIs offered by Internet leaders like Google, Flickr, Facebook, and others. If you have worked with any of those APIs, ours will be immediately familiar. The MN Open API gives you access to six million MP3 tracks from all major music labels and thousands of independent labels. The entire catalog of MP3 tracks is available for purchase and includes sample clips, album cover art, and a rich set of metadata. Instead of acquiring our metadata through the API dynamically, Customers can subscribe to the MediaNet XML Content Data Feed for a fee. The feed provides everything Customers need to know about our catalog, allowing Customers to flexibly program content as necessary. The feed is an XML Schema (XSD) -based file that we publish five days a week, M-Th and Sat. Content Partners provide new release content in advance, which appears in the feed with future dates so programming staffs can feature these releases on the street date, or promote them ahead of time. Please note that retail pricing and MN Open wholesale pricing information is not in the feed. These must be obtained in real-time from the API. These will be added to the feed in late Q1 2010.

In terms of transactions, you can utilize your own existing ecommerce solutions or choose to use our commerce:

Credit card payments - using the MN Open APIs to bill end-user’s credit cards for purchases. In this model, the retail price is set by us and you receive a revenue share on all transactions (deposited into your revenue share balance).

Account balance payments - deducting your wholesale cost from your account balance. In this model, you set the retail price and your wholesale content cost is deducted from your account balance.

Please see the Transaction Options section below for more information.

Our MN Open API is a REST-based1 HTTP service that is built on top of the MN Open Platform, our

enterprise-class media delivery technology giving you access to a rich media catalog. The API is stateless, easy to work with using any programming language, returns responses as XML or JSON, and includes all the transactional capabilities you need to create a complete music application.

In a nutshell, interacting with our API consists of: 1. An HTTP request, and 2. An HTTP response returned to the caller as either XML (default) or JSON

2.

At a more detailed level, it consists of:

Appropriate HTTP actions supported by the API: o GET to make calls where all parameters are provided in the URL (query string format

3)

o POST to make calls requiring large/complex data sets that cannot be provided in the URL

Parameters (scoping) will be specified in the query string and must be URL-encoded4

o Complex data will be sent using JSON or XML in the body of a POST. o URL (query string) parameter names and values are not case-sensitive. Element names

for XML-formatted POST bodies are case-sensitive. Example -- parameters are in bold:

http://api.mndigital.com?method=search.gettracks&artist=Pearl+Jam&page=1&pageSize=1

1 Representational State Transfer; please see http://en.wikipedia.org/wiki/REST

2 JavaScript Object Notation; please see http://en.wikipedia.org/wiki/JSON.

3 Query String; please see http://en.wikipedia.org/wiki/Query_string.

4 Also known as Percent Encoding. Please see http://en.wikipedia.org/wiki/URL_encoding.

http://en.wikipedia.org/wiki/REST

http://en.wikipedia.org/wiki/JSON

http://en.wikipedia.org/wiki/Query_string

http://en.wikipedia.org/wiki/URL_encoding


An HTTP response consisting of XML (MIME type text/XML) or JSON (MIME type text/javascript).

Errors, if any, are indicated within the HTTP response inside an XML- or JSON-formatted Error node (not to be confused with HTTP response codes). The Error node will contain a relevant MN Open API error code and human-friendly message. Please see the Common Errors section below.

To be clear: since the service is HTTP-based, all responses will have an HTTP protocol response code and status message

5 in addition to our API’s success and error messaging.

Security: Customer Authentication and Encryption

We will assign you an API Key and a Shared Secret.

API Key: This unique identifier will be required for all API calls. We will use this to authenticate and identify your account.

Shared Secret: This will be required for many API calls. It will be used to create a Signature: an HMAC-MD5 hash

6 of the query string. Your Shared Secret should be kept highly secure.

SSL: This will be required for any API calls with sensitive or transaction-related data. It will be implemented simply by calling the command using https:// instead of http://.

Keep your API Key and especially Shared Secret very secure. Please note client side solutions may expose your API key and or shared secret.

For more detail, please see Generating Signatures with your Shared Secret below.

Transaction Options

As mentioned above, you may use your own ecommerce solution or use ours. This section describes in greater detail how credit card payments and account balance payments work. There is also discussion about pricing and tax collection and reporting.

Credit Card Payments To offer conventional credit card payments to end users, you can use the MN Open Provisioning APIs, which features support for all major credit cards (Visa, MasterCard, Discover, and American Express), industry-standard encryption and security, shopping cart functionality, a la carte transactions, and more. The complexity is handled for you by MN Open. Transactions will appear on end user credit card statements as "MP3 Downloads" until later in 2009 when this text will become customizable by you.

You can use the User methods in our API in order to manage your end users, including storing their credit card number for future purchases.

When using our MN Open commerce functionality, the retail price for each item is returned to you in the Content Discovery APIs. Each purchase made using our credit card processing will earn you a revenue share. Your revenue share is based on the retail cost for each item sold, excluding taxes and other fees. The credit card processing transaction fees are absorbed by us.

The revenue share earned on each transaction is deposited into your revenue share account (maintained separately from your regular account balance). We apply a 30-day hold on all revenue share transactions to protect against fraud; e.g., to ensure that an end user does not issue a chargeback for a transaction. After the 30 days, the revenue share is available for you to either transfer into your regular account balance or for withdrawal.

5 For details on HTTP status codes, see http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

6 Please see http://en.wikipedia.org/wiki/HMAC-MD5

http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

http://en.wikipedia.org/wiki/HMAC-MD5


Credit card payments are currently available only for card holders residing (billing address) in the United States.

Account Balance Payments

A second option for processing transactions is using our account balance system. You can deposit funds into your account balance using a credit card at initial set up or any time thereafter (there is a 3% processing fee), via the Partner.RefillBalance API, or check. To fund or refill by check, please contact us directly via [email protected].

With this payment model, every purchase transaction is deducted against your account balance. The amount deducted for each transaction is your wholesale cost for the content which is exposed to you within the Content Discovery APIs. We also expose Management APIs that allow you to retrieve your account balance at any time: Partner.GetBalance.

With this model, and using your own commerce system, you are free to set the end-user retail price at any amount, with certain exceptions described below.

Pricing, Required Retail Price and Tax Handling

When you retrieve metadata via the Search APIs, it will be accompanied by your Wholesale Cost and a Suggested Retail Price (SRP). When using your own commerce system (per the discussion above), you may set your own retail prices. Please note that some content is accompanied by a Required Retail Price (Sony, WMG, and UMG)

7, as well as the requirement to collect and report tax in certain states (Sony

only). The Required Retail Price will be indicated as another element in Search responses: IsSetPrice=True.

Example "PriceTag": {

"Currency": 1,

"Amount": 1.29,

"IsSetPrice": true,

"Wholesale": 1.02

},

When present, the value from the Amount element must be used. When it is Sony content (indicated by LabelOwnerId=3), two additional requirements must be met (these are part of the so-called Sony Agency Model):

You must report the end user's city, state, and zip code, as well as the amount of tax collected with any purchases of such content

You can use the Label.GetLabelOwners API call to get a current list of Label owners. i.e. http://ie-api.mndigital.com?method=Label.GetLabelOwners&format=xml&apiKey=yourapikey. Please see Appendix B for more details.

You must add to any checkout page, receipt pages, and receipt emails that contain Sony content the following text string exactly as written -- no changes are acceptable:

"Any permanent downloads of Sony Music Entertainment products are sold directly by Sony Music Entertainment Digital LLC via MediaNet Digital, Inc. as its agent."

At the time of writing, tax must be collected for such content only from residents of Texas (and again, only for Sony content). Please see Appendix A: Sony Agency Model Nexuses and Tax Rates.

7 Currently this applies to any content owned by Sony (LabelOwnerId=3), Warner/WMG

(LabelOwnerId=1) and UMG (LabelOwnerId=5) and may apply to others in the future. Recommendation: implement in code that any appearance of IsSetPrice=True must be observed.

mailto:[email protected]

http://ie-api.mndigital.com/?method=Label.GetLabelOwners&format=xml&apiKey=yourapikey



In the future we will offer an API by which to stay up-to-date on the tax and rate requirements programmatically.

In the credit card payment model, we handle the tax calculation and rule enforcement, and any tax collected will be excluded from revenue share calculations. In the account balance payment model, taxes owed (Texas and only for Sony content) will be further deducted from your balance. In this case, you would collect the taxes directly from your end-user and we will deduct the tax from your account balance to be passed through to the appropriate content owner.

Please note that any other tax you collect (i.e., from within their own state or other obligations) does not need to be reported via our APIs. Please see the Purchase.UseBalance notes for more information.

Territory Restriction

All content available via the MN Open APIs is only available for sale in the United States. For your convenience, we make an API available (Search.GetGeoLocation) that will give you the end user’s country based on their IP address. In the future, we plan on making other territories available.

Album / Track revocation

From time to time, the full set of albums and tracks that are available through the API may change as albums and tracks are added to, or deleted from, the full catalog offerings. MediaNet receives content rights updates and requests for content removals on a daily basis and your application needs to take this into account. There are several reasons: some are due to rights changes by a content owner or because of ownership conflicts.

Bitrate information All content available via the MN Open APIs is 320kbps except for Sony and Warner content, which is 256kbps. In other words, about 85-90% of our catalog is at the higher quality 320kbps. The following is a “track” node XML snippet which was returned from the Album.GetTracks API using mnetId=26685813. Please note the <Bitrate>320kb</Bitrate> element, yellow-highlighted below.

<Track>

<MnetId>26685817</MnetId>

<Title>Bellimbusto (Radio Mix)</Title>

- <Artist>


<Name>Creamminals</Name>

- <Images>

<Artist180x80>http://images.musicnet.com/artists/000/637/321/b.jpeg</Ar

tist180x80>

</Images>

</Artist>

<Genre>Electronica/Dance</Genre>

<ExplicitLyrics>false</ExplicitLyrics>

<Duration>5:11</Duration>

<ReleaseDate>03-14-2009</ReleaseDate>

<TrackNumber>2</TrackNumber>

<DiscNumber>1</DiscNumber>

- <PriceTag>

………….

</PriceTag>

- <Mp3Rights>

<CanSampleStream>true</CanSampleStream>


<CanPurchaseDownload>true</CanPurchaseDownload>

<AlbumPurchaseOnly>false</AlbumPurchaseOnly>

</Mp3Rights>

<FeaturedArtists i:nil="true" />

<Bitrate>320kb</Bitrate>

</Track>


MN Open API Best Practices Checklist 1. When reporting possible issues with the API calls, please include:

a. Your repro steps b. Your expected and actual results (XML, Json), c. Your API requests and responses, including your full URL d. The full query that you are using.

2. Keep your API Key and especially Shared Secret very secure. Note that some client side implementations may expose your API key or shared secret.

3. Required Retail Price - observe the IsSetPrice flag. 4. For Sony content

a. Collect tax where appropriate (texas). b. Report City, State and Zip in your purchase API calls. c. Include in checkout pages, receipt pages, and receipt emails the Sony Agency text.

If you use caching for a portion of the catalog, refresh the cache at least once a day to avoid any issues with Album or Track Revocation.

5. When displaying Artist Images be sure to test for any 404s, in case the image is not yet available.

6. For parsing XML responses, use a standard XMLDOM/XMLReader for accessing the XML responses, rather than a rigid or hard coded scheme. A set of code examples are provided to help illustrate possible use of XML DOMs.

7. Observe the AlbumPurchaseOnly flag. Some tracks are only available as part of an album 8. If using wildcards with the Album, Artist, Search, and Track packages, be sure to use Paging

responsibly to avoid the risk timeouts. 9. For more exact searches of Albums, include Search.GetAlbums mainArtistOnly flag, otherwise

you may get some “tribute” albums by design 10. For APIs that request UserDomain or SiteDomain parameters, submit the domain or host name

(site) where the sale originated from. 11. Other APIs request the UserIP; submit as accurate an IP as possible. 12. If you use Partner.GetAMGData, be sure to always use the Google Analytics snippets returned by

the API in your code. 13. Instead of acquiring our metadata through the API dynamically, Customers can subscribe to the

MediaNet XML Content Data Feed. The feed provides everything Customers need to know about our catalog, allowing Customers to flexibly program content as necessary. The feed is an XML Schema (XSD) -based file that we publish five days a week, M-Th and Sat. Content Partners provide new release content in advance, which appears in the feed with future dates so programming staffs can feature these releases on the street date, or promote them ahead of time. Please note that retail pricing and MN Open wholesale pricing information is not in the feed. These must be obtained in real-time from the API. These will be added to the feed in late Q1 2010.


MN Open API Metadata The following pieces of metadata are exposed via the MN Open API. Most are common across methods, but some come back only from one or a handful of the API. Metadata Item Description Notes (page nums in API doc)

Album Art URLs Paths to album images

Album MnetID Unique identifier for an album MnetID is our catalog primary key for everything

Album Reviews From Allmusicguide.com See page 49 for terms and fees

Album Title Name of an album

Artist Name of an arist

Artist Art URLs Paths to artist images

Artist Bio From Allmusicguide.com See page 49 for terms and fees

Artist MnetID Unique identifier for an artist

Bitrate 256 or 320kbps See page 6

DiscNumber To account for sets of discs

Duration (track) Track time in minutes and seconds

Duration (album) Total time for an album

Explicit Lyrics (Boolean)

FeaturedArtists Secondary artists for a work

Genre MediaNet tracks 23 genres Alternative/Indie, Blues, Cast Recordings/Cabaret, Children's, Christian/Gospel, Classical/Opera, Comedy/Spoken Word, Country, Electronica/Dance, Folk, Instrumental, Jazz, Latin, New Age, Pop, Rap/Hip Hop, Reggae/Ska, Rock, Seasonal, Soul/R&B, Soundtracks, Vocal, World

Label The string representation of the Content Provider name

LabelOwnerId Numeric representation of Content Provider

Some Content Providers are owned by other Content Providers. This field shows which company is the ultimate "parent" owner.

Mp3Rights, containing:

CanSampleStream

CanPurchaseDownload

AlbumPurchaseOnly

(Boolean) (Boolean) (Boolean)

NumberOfTracks Total number of tracks in an album

PopularityRanking Rank of a work in the catalog Updated weekly

PriceTag, containing:

Currency

Amount

IsSetPrice

Wholesale

(Boolean)

See page 5 about IsSetPrice=true case

ReleaseDate The digital release date Not the same as the original, physical release date, which will be added late November 2009

ReleaseDate (at track level) The digital release date

SampleLocations, containing:

MediaLocation

MnetID

Location

Resource

The path to the sample for a track See page 13 for more info

Track MnetID Unique identifier for a track

Track Title Title of a track

TrackNumber On a given disc Example: Track 3 of 8 total on album


The MN Open APIs

The MN Open APIs expose various methods that are organized into the following packages, grouped by their high level functionality:

Content Discovery

Search

Track

Album

Artist

Provisioning

User

Cart

Purchase

Management

Partner

Report

Method calls will always return a Success node (set to "true") on success, or return an Error node that contains both a numerical error identifier and a human-friendly error description.

Let's show a simple example: Searching for tracks by Nirvana with the Search.GetTracks method, asking for a limited number of results, in JSON response format. The API will return core metadata about each track, plus artist and album art in multiple image sizes, as well as 30-second sample location information that is ready to be consumed by any Flash-based media player.

Example with Search.GetTracks Request via HTTP GET http://api.mndigital.com?method=search.gettracks&title=Come%20As%20You%20Are&artist=Nirvana &rights=purchase&includeExplicit=true&page=1&pageSize=1&apiKey=YourAPIKEY&format=json

Note that the first line is the HTTP response code and message, followed by the requested data in the body of the HTTP response, here formatted by request in JSON.

Response in JSON format Status: [200] OK {"Success": true,

"TotalResults": 5,

"Tracks": [

{"MnetId": "568959",

"Title": "Come As You Are",

"Artist": {

"MnetId": "24496",

"Name": "Nirvana",

"Images": {

"Artist180x80":"http:\/\/images.musicnet.com\/artists\/000\/024\/496\/b.jpeg",

"Artist190x230":"http:\/\/images.musicnet.com\/artists\/000\/024\/496\/c.jpeg",

"Artist375x250":"http:\/\/images.musicnet.com\/artists\/000\/024\/496\/a.jpeg"

"Artist200x":"http:\/\/images.musicnet.com\/artists\/000\/024\/496\/f.jpeg"

}

},

"Genre": "Alternative\/Indie",

"ExplicitLyrics": false,

"Duration": "3:38",


"ReleaseDate": "01-01-1991",

"TrackNumber": 3,

"DiscNumber": 1,

"PriceTag": {

"Currency": 1,

"Amount": 1.29,

"IsSetPrice": true,

"Wholesale": 1.02

},

"Mp3Rights": {

"CanSampleStream": true,

"CanPurchaseDownload": true

"AlbumPurchaseOnly": false },

"FeaturedArtists": null,

"Album": {

"MnetId": "568941",

"Title": "Nevermind",

"Artist": null,

"Genre": "Alternative\/Indie",

"ExplicitLyrics": false,

"Label": "Geffen",

"Duration": "42:23",

"ReleaseDate": "01-01-1991",

"NumberOfTracks": 12,

"Images": {

"Album75x75":"http:\/\/images.musicnet.com\/albums\/000\/568\/941\/s.jpeg",

"Album150x150":"http:\/\/images.musicnet.com\/albums\/000\/568\/941\/m.jpeg",

"Album800x800":"http:\/\/images.musicnet.com\/albums\/000\/568\/941\/g.jpeg"

},

"FeaturedArtists": null,

"LabelOwnerId": 5,

}

"SampleLocations": [

{"MnetId":"568959",

"Location":"rtmp:\/\/DMUS.flash-prod.musicnet.com:80\/Sample",

"Resource":" mp3:\/spl\/000\/568\/959\/spl_024" }

]},

{"MnetId":"745367",

"Title":...

}

]}

Here is the same response data in the (default) XML response format. Again, note that the first line is the HTTP response code and message, followed by the HTTP response body containing the data in XML. The best practice for parsing XML responses is to use a standard XMLReader for accessing the XML responses, rather than a rigid or hard coded schema generated by the customer.

Response in XML format (the default response format) Status: [200] OK <TrackSearchResults xmlns="http://api.mndigital.com"

xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<Success>true</Success>

<TotalResults>5</TotalResults>

<Tracks>

<Track>


<Title>Come As You Are</Title>

<Artist>


<Name>Nirvana</Name>

<Images>

<Artist180x80>http://images.musicnet.com/artists/000/024/496/b.jpeg</Artist180x80>

<Artist190x230>http://images.musicnet.com/artists/000/024/496/c.jpeg</Artist190x230>

<Artist375x250>http://images.musicnet.com/artists/000/024/496/a.jpeg</Artist375x250>

<Artist200x>http://images.musicnet.com/artists/000/024/496/f.jpeg</Artist200x>

</Images>

</Artist>

<Genre>Alternative/Indie</Genre>






<PriceTag>

<Currency>USD</Currency>

<Amount>1.29</Amount>

<IsSetPrice>true</Wholesale>

<Wholesale>1.02</Wholesale>

</PriceTag>

<Mp3Rights>




</Mp3Rights>

<FeaturedArtists i:nil="true"/>

<Album>


<Title>Nevermind</Title>

<Artist i:nil="true" />

<Genre>Alternative/Indie</Genre>


<Label>Geffen</Label>



<NumberOfTracks>12</NumberOfTracks>

<Images>

<Album75x75>http://images.musicnet.com/albums/000/568/941/s.jpeg</Album75x75>

<Album150x150>http://images.musicnet.com/albums/000/568/941/m.jpeg</Album150x150>

<Album800x800>http://images.musicnet.com/albums/000/568/941/g.jpeg</Album800x800>

</Images>


<LabelOwnerId>5</LabelOwnerId>

</Album>

<SampleLocations>

<MediaLocation>


<Location>rtmp://DMUS.flash.musicnet.com:80/Sample</Location>

<Resource>mp3:/spl/000/568/959/spl_024</Resource>

</MediaLocation>

</SampleLocations>

</Track>

<Track>


<Title>Come As You Are (Live)</Title>



</Track>

</Tracks>

</TrackSearchResults>


MN Open API Package and Method Overview The following chart provides a summary of each package and each of its associated methods including a description of functionality, as well as Signature and SSL requirements.

Package/Method Description Signature Required?

SSL Required?

Content Discovery

Search Package Contains methods for searching the MediaNet catalog.

GetTracks Searches for tracks by title, artist, album, and/or keyword. Can filter by available rights. Can choose to includeExplicit (default=true). Returns track matches including artist and artist images, album and album art, and 30-second sample locations

No No

GetAlbums Searches for albums by title, artist, and/or keyword. Can filter by available rights. Can choose to includeExplicit (default=true). Returns album matches with tracks including artist and artist images, and album and album art, and 30-second sample locations like GetTracks.

No No

GetArtists Searches for artists by name and/or keyword. Returns artist matches and artist images if any

No No

GetGeoLocation Does a lookup by IP. Returns two-letter country code (ISO 3166

8)

No No

ContentMatch Returns the single best track matched in real-time based on one or more input parameters, using a sophisticated matching algorithm. Parameters include: title, artist, album, ISRC, AMG ID, UPC. Can filter by available rights. Can choose to includeExplicit (default=true). Returns the single best track match, if any, and 30-second sample locations like GetTracks.

No No

Track Package Contains methods for retrieving information about a track.

Get Retrieves by MediaNetID (mnetid) the metadata about a specific track, including artist and album info, etc.

No No

GetLocations Retrieves media locations for 30-second samples.

Yes No

Album Package Contains methods for retrieving information about an album.

GetTracks Retrieves by MediaNetID (mnetid) the metadata about a specific album, including artist and album info, with tracks, etc.

No No

Label Package Contains methods for retrieving information about an artist.

GetLabelOwners Retrieves label owener name and ids for all labels available through the API.

No No

8 http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2



SSL Required?

Artist Package Contains methods for retrieving information about an artist.

GetAlbums Retrieves by MediaNetID (mnetid) the metadata about an artist's albums, including artist and album art, etc. Can filter by available rights (default=true). Can choose to includeExplicit. Note: Track information is not returned.

No No

GetTracks Retrieves by MediaNetID (mnetid) the metadata about an artist's tracks, including artist art, etc. Can filter by available rights. Can choose to includeExplicit (default=true). Note: Album information is not returned.

No No

Provisioning

User Package Contains methods for creating, updating, and authenticating user accounts.

Create Creates a user associated with your PartnerID Returns the user's details

Yes Yes

Get Retrieves information about a specific user Returns the user's details

No No

IsUsernameAvailable Checks whether a username is available Usernames are unique by customer.

No No

Login DEPRECATED Logs in a user by username and password Returns an Auth Token

Yes Yes

SetPassword Sets (changes) a user's password. Yes Yes

Update Updates (changes) information about a specific user.

Yes Yes

Cart Package Contains methods for creating, updating, and purchasing items.

AddItems Adds an item to cart. If no CartId is referenced, a new one is created. Returns an existing or new CartId, plus a count of items in the cart.

Yes No

Clear Clears (empties) an existing CartId Yes No

Get Retrieves the details of a specific cart. Returns sub-total, tax, total, and line items including track and album info, and artist and album art

Yes No

GetCartByUser Retrieves a CartId, if any, associated to a user, including the line item(s) in it, along with sub-total, tax, and grand total.

Yes No

GetDownloadLocations Retrieves the media download locations (URLs) for objects in an OrderID (see Cart.Purchase below)

Yes No

Purchase Purchases a cart, using a credit card. Returns (on success) an OrderID to reference by GetDownloadLocations (see above). For purchases without a cart, see the Purchase package below.

Yes Yes

RemoveItems Removes one or more item(s) from an existing cart.

Yes No



SSL Required?

Purchase Package Contains methods for purchasing outside a shopping cart paradigm.

UseBalance Purchases a single or multiple tracks and/or albums in a single transaction, debiting your Account Balance. For purchases utilizing our shopping cart functionality, see Cart.Purchase above.

Yes Yes

UseCreditCard Purchases a single or multiple tracks and/or albums, using a credit card. For purchases utilizing our shopping cart functionality, see Cart.Purchase above.

Yes Yes

Management

Partner Package Contains methods for managing your account balance

GetAMGData Retrieves AMG biography for an artist and/or AMG review for an album

Yes No

GetBalance Retrieves your current account balance Yes No

RefillBalance Refills (or adds to) your account balance. Please note that we charge a 3% convenience fee for credit card refills.

Yes No

Report Package Contains methods for generating reports.

GetOrderHistory Retrieves orders by end user username within a range of "start" and "end" dates

Yes No

Global Parameters Required for all methods:

APIKey

Method name

Required for some methods:

Signature (some also require use of https)

Optional

ResponseType (XML (default) or JSON)

Paging

Many methods include two attributes: Page and PageSize

Page: The page number that should be retrieved.

PageSize: The number of items per page.

This design supports paging through a long list of results broken into pages. For example, if a search returns 100 results, you can choose to receive them all at once or broken across N pages.

Page=1 and PageSize=100 will place all 100 results on one page

Page=10 and PageSize=10 will return the last 10 results

Page=5 and PageSize=50 will return no results, since this is asking for the 201st to 250th results of a 100-item result set.

Generating Signatures with your Shared Secret

All parts of a query string except the signature must be hashed. All symbols inside the query string (ampersands, pipes, etc.) need to be added. The question mark before the query string is not included (it's not part of the query string; it indicates the beginning of the query string). Also, the Signature


parameter itself is not included. In other words, the input should be the query string exactly as sent minus the Signature parameter. The Signature should be a HMAC-MD5 hex digest.

Example In the following Purchase.UseCreditCard call, the green-highlighted portion is what should be hashed, transformed, and submitted as the Signature parameter.

http://api.mndigital.com?method=purchase.usecreditcard&apiKey=YourApiKey&format=xml&userIP=enduserIPAddress&siteDomain=domainname&signature=c8443d830782243cc23d0448c7774fea

If you have code already for performing the HMAC-MD5 transformation, then it might look like this:

Signature=HMACMD5("method=purchase.usecreditcard&apiKey=YourApiKey&format=xml&userIP=enduserIPAddress&siteDomain=domainname")

Please note: in this example, the Shared Secret is "inside" the HMACMD5() method, whether hard-coded or retrieved programmatically. A common version of HMAC-MD5 in PHP on the web looks like this:

hash_hmac('md5', $string, $key)

...where $string is the query string and $key is the shared secret.

You may need to URL-encode the query string before performing the hash. For example, the pipe symbols that appear in the &mnetid parameter in Track.GetLocations must be URL-encoded first. In PHP the code would like like this:

$theQuery = $theQuery."&signature=".hash_hmac('md5', $theQuery, $yoursharedsecret);

A version of HMAC-MD5 in JQuery on the web is at http://plugins.jquery.com/project/md5

A version of HMAC-MD5 in PHP on the web is at http://www.php.net/manual/en/function.hash-hmac.php

If you need to URL-encode a string, for example, the pipe symbols that appear in the &mnetid parameter in Track.GetLocations see.

A version of JQuery $.URLDecode is at http://plugins.jquery.com/project/URLEncode

A version of PHP $.URLDecode is at http://us3.php.net/urlencode

.

Tips for Methods That Require a POST Body Some methods require the use of an HTTP POST to pass large and/or complex amounts of data into our APIs. Please see the footnotes on page 3 for more about JSON. If using XML, please remember that XML is case-sensitive. Pay careful attention to the code samples below and the casing of the elements to be passed in the POST bodies. The MN Open API expects all elements to be Pascal case aka UpperCamelCase.

9 XML is also order-dependent (unlike JSON) so ensure the elements in your POST

bodies match what's in the documentation examples below. If you find yourself receiving errors about

9 http://en.wikipedia.org/wiki/Pascal_case

http://api.mndigital.com/?method=purchase.usecreditcard&apiKey=YourApiKey&format=xml&userIP=enduserIPAddress&siteDomain=domainname&signature=c8443d830782243cc23d0448c7774fea



http://plugins.jquery.com/project/md5

http://www.php.net/manual/en/function.hash-hmac.php

http://www.php.net/manual/en/function.hash-hmac.php

http://plugins.jquery.com/project/URLEncode

http://us3.php.net/urlencode

http://en.wikipedia.org/wiki/Pascal_case


"element X is missing" even though you are passing it in, double-check both the case and order of the elements against the examples.

Streaming Samples with Flash: RESOURCE and LOCATION

For security and stability purposes, MediaNet Digital delivers 30-second MP3 samples via Flash Media Streaming (FMS). The MN Open API returns the MP3 sample in two parts: Resource and Location. (This division is an integral part of the Adobe Flash Media Streaming solution.) For an example, here is the relevant portion from the Search.GetTracks call on page 7-8 above (proper nesting adjusted for readability): <SampleLocations>

<MediaLocation>




</MediaLocation>

</SampleLocations>

Real-Time Messaging Protocol (RTMP) is part of the proprietary Adobe FMS solution.

Submit the two parts, Location and Resource, as separate arguments to your Flash-capable streaming player. The player then assembles the final URL itself internally and plays the stream. In other words, while sourcing media player components for your application, ensure that it supports Adobe FMS with RTMP. Please see the following for more detail: http://www.adobe.com/devnet/flashmediaserver/articles/overview_streaming_fms3_02.html

We host a "test player" that you can use to test the sample media locations that we return at http://widgets.mndigital.com/test/stream.aspx

PHP, cUrl, and Content-type Header Setting

If you are using PHP with cUrl, make sure that you set the header of each request to match the format parameter in the request. That is, the content-type header of the request must be set to XML or JSON; i.e., it must match what you set in the query string &format parameter. It cannot be something else or you will receive errors.

For XML response: Content-Type: application/xml

For JSON response: Content-Type: application/json

Download Locations and Single Download

Due to security restrictions imposed by the Labels (content owners), content purchased from the MediaNet Platform is available as follows:

Permanent Download Locations (PDLs) for full tracks are valid for eight (8) hours10

Each track may be downloaded only once (enforced by MediaNet download servers)

We recommend that you encourage end users to download their content immediately.

10 Coming soon there will be an API to get download locations (again) for content that has been already

purchased but not yet downloaded. Full permanent aka purchase track locations will remain valid for one year. Sample locations do not expire.

http://www.adobe.com/devnet/flashmediaserver/articles/overview_streaming_fms3_02.html

http://widgets.mndigital.com/test/stream.aspx


Samples are typically of short (~30 second) length. Download locations for samples: <sampleMediaLocations> are returned in response to most search APIs, such as when searching for tracks of an album. In September 2009, the format of sample locations will change, namely the value of the RESOURCE tags. The new format of download locations for samples will be CompID XXXYYYZZZ; for example: mp3:/spl/XXX/YYY/ZZZ/spl_024.

Please see XML below for an example of LOCATION and

RESOURCE tags returned in <sampleMediaLocations>. <SampleLocations>

<MediaLocation>




</MediaLocation>

</SampleLocations>

The same sample in the older format for RESOURCE is: mp3:/mp3/tk6070c1b/mn_mp3_07_11/streams/a024/000/568/568959_024.

Environments: Integration (IE) and Production (PROD) MediaNet Digital maintains two wholly separate environments for use by customers. Customers (Partners) will receive two sets of keys, one per environment.

Environment Credit card processing Fulfillment

Integration (IE) http://ie-api.mndigital.com

Not live; test card numbers are acceptable, e.g., Visa: 4111111111111111 MasterCard: 5500000000000004 AmEx: 340000000000009 Discover: 6011000000000004

The same one dummy download locations is returned for all purchases: http://DMUS.download-ie.musicnet.com/sample/download/location/

Production (PROD) http://api.mndigital.com

Live cards Real content is provided by real download locations. For low-cost testing in PROD, a special MediaNet-owned album with four tracks has been created. The album is $0.69 ($0.20 wholesale) and the tracks are $0.69 ($0.10 wholesale) each. (The prices cover our credit card processing fees.)

Album MnetId 30750261

Artist: MN Open Title: Sample

How to Search for International Language Data

Concisely, the MediaNet Platform stores metadata about the content in the Catalog in Unicode. To find international language data, you must query by URL-encoding the UTF-8 version of any international language strings. Please read on for more detail.

The Platform stores metadata about our content in Unicode, and in spite of having content primarily for the US, CA, DE, FR, and UK territories "only," we do have artists, titles, and corresponding additional metadata in many other languages: European, Eastern European, Arabic, Hebrew, Japanese, Chinese, etc., particularly in our World and Folk music genres. Note that often in each field (e.g., track title, album title, artist title) there will be both the original "native" or international language as well as an English transcription -- one or the other may be in parentheses. In addition, since our search indexes contain both

http://ie-api.mndigital.com/

http://api.mndigital.com/


the "native" and normalized formats (stripped of accents, etc.), content can often be found with either an English (ASCII) transcription or the native language script (in Unicode). As an example, here's part of the response to Search.GetTracks. In yellow-highlight are some fields that contain Russian (in Cyrillic and an English transliteration): <Tracks>

<Track>


<Title>Ya Pela Dlya Tebya (Я пела для тебя)</Title>

<Artist>


<Name>Валерия Коренная (Valeriya Korennaya)</Name>

<Images>





</Images>

</Artist>

<Genre>World</Genre>






<PriceTag>



<IsSetPrice>false</IsSetPrice>

<WholesalePrice>0.82</WholesalePrice>

</PriceTag>

<Mp3Rights>



</Mp3Rights>

<FeaturedArtists i:nil="true"></FeaturedArtists>

<Album>


<Title>Качели Моего Двора (Kacheli Moego Dvora)</Title>

<Artist i:nil="true"></Artist>

<Genre>World</Genre>


...(truncated for space reasons)

To perform this search: you must use UTF-8 and URL-encode it.

Example with Search.GetTracks for the string Коренная (Cyrillic for "Korennaya") (truncating the unimportant parameters from the URL):

http://api.mndigital.com?method=Search.GetTracks&format=xml&title=&album=&albumMnetId=&artist=%D0%9A%D0%BE%D1%80%D0%B5%D0%BD%D0%BD%D0%B0%D1%8F...

The green-highlighted portion is the sequence of eight two-character representations for each of the eight Cyrillic letters from the Russian string.

Response: the example shown above on the previous page.

A simple example would be for the proper form of "Beyoncé" -- ideally, the accented "e" would get URL-encoded, too:

http://images.musicnet.com/artists/000/557/635/b.jpeg%3c/Artist180x80

http://images.musicnet.com/artists/000/557/635/c.jpeg%3c/Artist190x230

http://images.musicnet.com/artists/000/557/635/a.jpeg%3c/Artist375x250

http://images.musicnet.com/artists/000/557/635/f.jpeg%3c/Artist200x


http://api.mndigital.com?method=Search.GetTracks&format=xml&title=&album=&albumMnetId=&artist=Beyonc%C3%A9

Response: results for Beyoncé

One final note: as mentioned above, for popular artists like Beyoncé, in our Search indexes we store a "normalized" version (in this case without the accented e) so that we will still find Beyoncé even if the query string is "Beyonce".

Handling Album-only Tracks You will receive the following error message “200 : Track Pricing Information not found “ when attempting to purchase a track that is album-only. Tracks that are purchasable only with album purchases will return:

<CanPurchaseDownload>true</CanPurchaseDownload> as well as <AlbumPurchaseOnly>true</AlbumPurchaseOnly>.

Friendly Filenames

Until this release, performing downloads using only a web browser, often resulted in meaningless and/or confusing filenames such as:getFile, getFile.wma, or getFile.mp3. With the release of Friendly Filename Feature, we now provide "friendly" and meaningful filenames to users such as “The Police - Synchronicity (Remastered) - 1 - 7 - Every Breath You Take.mp3”.

When the Friendly Filename Feature is enabled, calls to GetMediaLocation will return a location URL that includes the encoded Friendly Filename information. For example:http://savvis.download-prod.musicnet.com/getFile?filename=Elvis+Presley+-+I+Believe+-+The+Gospel+Masters+-+1+-+1+-+I+Believe.wma&file=n6Wvo7CCRk2nTxVq+PUZIQ==&token=e4435f71a643349c77ecf1c3081148df584ef6ad8ad754cfecefda7f67eeeb2f7a9b3ed7aaebe4fe85c3b3ae9da589380db99afc039a0931bd8b4106f044edaefdaf8b0cdccbcf5f2fba62367e56c07daadfe811dd60c420a551f2f76018a8d5

Image Data

MediaNet has album art in multiple sizes for all assets in the catalog. In addition, we have artist images for about 20,000 artists (the "f" size). The top 5000 most popular artists have multiple sizes; see below.

Album Art

75x75 - the "s.jpeg"

150x150 - the "m.jpeg"

800x800 - the "g.jpeg"

Artist Art Please check for error 404 when an Artist Art is not available.

180x80 - the "b.jpeg"

190x230 - the "c.jpeg"

375x250 - the "a.jpeg" 200x - the "f.jpeg" (please note the height is variable, hence the absence of a specifier)

Common Response Data Elements

Search, Track, Album, and Artist Packages Data Types

Track

string MnetId

string Title

Artist Artist

http://savvis.download-prod.musicnet.com/getFile?filename=Elvis+Presley+-+I+Believe+-+The+Gospel+Masters+-+1+-+1+-+I+Believe.wma&file=n6Wvo7CCRk2nTxVq+PUZIQ==&token=e4435f71a643349c77ecf1c3081148df584ef6ad8ad754cfecefda7f67eeeb2f7a9b3ed7aaebe4fe85c3b3ae9da589380db99afc039a0931bd8b4106f044edaefdaf8b0cdccbcf5f2fba62367e56c07daadfe811dd60c420a551f2f76018a8d5






o MnetId and Name

Artist[] Featured Artists o MnetId and Name

Album Album o MnetId, Title, Genre, Explicit Lyrics, Duration, Label, and Release Date (no Tracks, no

Performers)

string Genre

bool Explicit Lyrics

string Duration (formatted for display- mm:ss)

string Release Date

int Disc Number

int Track Number

string Error

bool Success

Album

string MnetId

string Title

Track[] Tracks o MnetId, Title, Genre, Explicit Lyrics, Duration, Label, and Release Date (no Album, no

Performers)

Artist Artist o MnetId and Name

Artist[] Featured Artists o MnetId and Name

string Genre

bool Explicit Lyrics

string Duration (formatted for display- mm:ss)

string Label

string Release Date

int Track Count

int Disc Count

int LabelOwnerId

string Error

bool Success

Artist

string MnetId

string Name

Album[] Albums o MnetId, Title, Genre, Explicit Lyrics, Duration, Label, and Release Date (no Tracks, no

Performers)

Track[] Tracks o MnetId, Title, Genre, Explicit Lyrics, Duration, Label, and Release Date (no Album, no

Performers)

string Error

bool Success

ContentMatch

Track Track

string Error

bool Success


MediaLocations

MediaLocation[] Locations

string Error

bool Success

Purchase Package Data Types

PurchaseUseBalanceResults

Order Order

string Error

bool Success

PurchaseUseCreditCardResults

Order Order

string Error

bool Success

Report and User Package Data Types

User

string ID

string FirstName

string LastName

string Username

string EmailAddress

string PartnerPID (Partner ID)

Boolean AllowNewsletter

Boolean AllowHtmlEmail

string Error

bool Success

SessionInfo

string AuthToken

string Error

bool Success

OrderResults

Order[] Orders

int TotalResults

string Error

bool Success

Cart Data Types

CartItemCount

Int CartId

int Count

string Error

bool Success


ShoppingCart

Int CartId

double SubTotal

double Tax

double Total

LineItem[] Items

string Error

bool Success

CartClearResult

string Error

bool Success

LineItem

string MnetId

string ItemType

double Price

double Tax

string Title

ItemTypes

Track

Album

DownloadLocationResults

MediaLocation[] DownloadLocations

int TotalResults

string Error

bool Success

Order

Int DisplayId

string Date

string Time

double SubTotal

double Tax

double Total

LineItem[] Items

string Error

bool Success

User

string FirstName

string LastName

string EmailAddress

UserCartResponse

string CartId

decimal SubTotal

decimal Tax

decimal Total


LineItem[] Items

Error Error

bool Success

BillingAddress

string AddressLine1

string AddressLine2

string City

string State

string PostalCode

string Country

CreditCard

string FirstName

string LastName

string Number

string CVV

string CardType

int ExpirationMonth

int ExpirationYear

Partner Data Types

PartnerGetBalance

string AvailableBalance

PartnerRefillBalance

bool Success

AMGDataResults

string AMGDataResults

Common Errors Errors are indicated by testing the Success status field in the response for "true" for OK, and "false" for Errors. If false is received, then you will have to test the Error collection for errors in the form of code(s) and description(s). Each method summary will list its own method-specific exceptions, plus reference the following list of Common Exceptions.

MediaNet recommends that customers mask our errors for best end-user experience.

Status Code Error Text Cases 100 Application Error: An

unknown error occurred This means something fundamentally wrong with the request: malformed, missing parameters, incorrect format (content type), etc. Please double-check and try again.

105 Application Error: Exception from the Platform Layer

The MN Open API sits on top of the MediaNet Digital Enterprise Platform: Web Services and Catalog.

110 Application Error: Error from Data Access Layer

115 Application Error: Service temporarily unavailable

There was a timeout somewhere in the stack.


Status Code Error Text Cases 120 Application Error: Method

has not been implemented

200 Input Error: Invalid parameter

205 Invalid API key

210 Incorrect signature

300 Permissions error


Content Discovery

Search Package

Contains methods for searching the MediaNet catalog.

Important: Results for all Search methods are automatically sorted by popularity.

Search Package Summary:

GetTracks

GetAlbums

GetArtists

GetGeoLocation

ContentMatch

Search.GetTracks

Description: Searches for tracks by title, artist, album, and/or keyword. Can filter by available rights. Can choose to includeExplicit (default=true).

Returns: track matches (with a count) including artist and artist images, and album and album art Recommended HTTP Action: GET Signature or SSL Required? Neither

Parameters:

Name Description Required? Default Value Type

ApiKey Partner's API key Yes String

Method The name of the method to invoke. Yes String

Album The name of the album. No String

Artist The name of an artist. No String

Format The format the response should be in, JSON or XML.

No XML String (Values: XML, JSON)

IncludeExplicit Whether to include items with explicit content (title, lyrics).

No True Boolean

Keyword Search term to be used in a combined Album, Artist, and Track search that will return tracks

No String

Page The page number that should be retrieved

No 1 Integer

PageSize The number of items per page. No 5 Integer

Rights The content right to filter by. Possible values are: "purchase" and "sample." The default is "purchase," and is what is used if other material is passed in.

No purchase String (Values: purchase, sample)

Title The track's title. No String

Example: ?method=search.gettracks&artist=Pearl+Jam&page=1&pageSize=10&ApiKey=YourApiKey&rights=purchase


Returns: TrackSearchResults

Int TotalTracks

Track [] Tracks; see Common Response Data Elements above

Tracks are returned in order of popularity (e.g., <PopularityRanking>1</PopularityRanking> tag returned from the call), with 1 meaning the highest popularity.

From time to time, the full set of albums and tracks that are available through the API may change as albums and tracks are added to, or deleted from, the full catalog offerings.

Search.GetAlbums

Description: Searches for albums by title, artist, and/or keyword. Can filter by available rights. Can choose to includeExplicit (default=true).

Returns: album matches (with a count) with tracks Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:


ApiKey Partner's API key. Yes String

Method The name of the method to invoke.

Yes String





No True Boolean

Keyword Search term to be used in a combined Album, Artist, and Track search that will return albums

No String

mainArtistOnly ensures that results of a command contain only those where the specified artist is the primary or main artist

No false Boolean


No 1 Integer




Title The album's title. No String

Example: ?method=search.getalbums&artist=Pearl+Jam&mainArtistOnly=true&page=1&pageSize=10&ApiKey=YourApiKey&rights=purchase


Returns: AlbumSearchResults

Int TotalResults

Album [] Albums; see

Search.GetArtists

Description: Searches for artists by name and/or keyword. Returns: artist matches (with a count) and artist images if any Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:




Yes String



Keyword Search term to be used in a combined Album, Artist, and Track search that will return albums

No String

Name The name of an artist. No String


No 1 Integer


Example: ?method=search.getartists&name=Pearl+Jam&page=1&pageSize=10&ApiKey=YourApiKey

Returns: ArtistSearchResults

Int TotalResults

Artist [] Artists; see Common Response Data Elements above

From time to time, the full set of albums and tracks that are available through the API may change as albums and tracks are added to, or deleted from, the full catalog offerings.

Search.GetGeoLocation

Description: Does a lookup by IP Returns: Returns two-letter country code (ISO 3166

11)

Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:




Yes String

Addr The IP address to look up Yes String

11







Example: ?method=search.getgeolocation&addr=67.88.218.200&ApiKey=YourApiKey

Returns: Location (two-letter country code)

Search.ContentMatch

Description: Returns the single best track matched in real-time based on one or more of six input parameters, using a sophisticated matching algorithm. Parameters include: title, artist, album, ISRC, AMG ID, and UPC. Can filter by available rights. Can choose to includeExplicit (default=true). Use title with at least one of artist or album. UPC may be used in place of album title.Very Important: in query strings, the AMGID must be passed in using as many "%20" for spaces as exist in the AMGID itself; they vary.

Returns: the single best track match, if any Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:




Yes String

Album The album's title. No String

AMGID The AMG (All Music Guide) identifier for an asset Very Important: the AMGID must be passed in using as many "%20" for spaces as exist in the AMGID itself.

No String





No True Boolean

ISRC International Standard Recording Code. This is the international identification system for sound recordings and music video recordings. Each ISRC is a unique identifier for a specific recording, but the recording might appear on multiple albums.

No String


No Purchase String (Values: purchase, sample)



Title The track's title. Use title with at least one of artist or album. UPC may be used in place of album title.

No String

UPC Universal Product Code. Applies to albums, not tracks.

No String

Example: ?method=search.contentmatch&isrc={ISRC}&apiKey=YourApiKey&rights=purchase

Returns: ContentMatchResults

Track Track; see Common Response Data Elements above

Track Package

Contains methods for retrieving information about a track.

Track Package Summary:

Get

GetLocations

Track.Get

Description: Retrieves by MediaNetID (mnetid) the metadata about a specific track, including artist and album info, etc.

Returns: Track and Album information about the specified track. Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:

Name Description Required? Default Value Type ApiKey Partner's API key. Yes String




MnetId The MNetId for a track. Mnetid is returned in the various methods of the search package.

Yes String

Example: ?method=track.get&mnetId= 12296213&ApiKey=YourApiKey

Returns: TrackMetadata; see Common Response Data Elements above

Track.GetLocations

Description: Retrieves media locations for samples Returns: Media locations for one or more MNetIDs Required HTTP Action: GET Signature or SSL Required? Signature only.


Parameters:






mnetIds The MNetId for one or more Tracks. Delimited by '|' or ',' Note: if you use '|' you must URL-encode them before the hash.

Yes String



Signature All other query string parameters in an HMAC-MD5 hash. The Partner's Shared Secret is the key.

Yes String

Example: ?method=track.getLocations&mnetIds=13374|13375&rights=sample&apiKey=YourApiKey &signature=Signature

Returns: MediaLocations; see Common Response Data Elements above

Album Package

Contains methods for retrieving information about an album.

Album Package Summary:

GetTracks - album and track information

Album.GetTracks

Description: Retrieves a list of all tracks and their associated metadata for a given album. Returns: Album and Track information about the given album. Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:





MnetId The MNetId for an album. Mnetid is returned in the various methods of the search package.

Yes String

http://en.wikipedia.org/wiki/HMAC

http://en.wikipedia.org/wiki/Md5


Example: ?method=album.getTracks&mnetId=9565107&ApiKey=YourApiKey

Returns: AlbumMetadata; see Common Response Data Elements above

Label Package

Label.GetLabelOwner

Description: Retrieves all labels owners and associated label IDs. Returns: See Description. Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:


ApiKey Partner's API key. No String




Example: ?method=label.getLabelOwners&format=xml&ApiKey=YourApiKey

Returns: LabelOwnerresults, please see Appendix B for more details.

Artist Package

Contains methods for retrieving information about an artist.

Artist Package Summary:

GetAlbums

GetTracks

Artist.GetAlbums

Description: Retrieves by MediaNetID (mnetid) the metadata about an artist's albums, including artist and album art, etc. Can filter by available rights. Can choose to includeExplicit. Note: Track information is not returned

Returns: See Description. Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:


ApiKey Partner's API key. No String






IncludeExplicit Whether to include items with explicit content (title, lyrics). Shorten to explicit.

No True Boolean

MnetId The MNetId for an Artist. Mnetid is returned in the various methods of the search package.

Yes String


No 1 Integer

Pagesize The number of items per page. No 5 Integer



Example: ?method=artist.getAlbums&mnetId=43089&page=1&pageSize=10&rights=purchase&includeExplicit=true&ApiKey=YourApiKey

Returns: ArtistMetadata; see Common Response Data Elements above

Artist.GetTracks

Description: Retrieves by MediaNetID (mnetid) the metadata about an artist's tracks, including artist art, etc. Does not include album metadata. Can filter by available rights. Can choose to includeExplicit.

Returns: See Description. Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:






IncludeExplicit Whether to include items with explicit content (title, lyrics). Shorten to explicit.

No True Boolean

MnetId The MNetId for an Artist. Mnetid is returned in the various methods of the search package.

Yes String


1 Integer

PageSize The number of items per page. 5 Integer





Example: ?method=artist.getTracks&mnetId=43089&page=1&pageSize=10&rights=purchase&includeExplicit=true&ApiKey=YourApiKey

Returns: ArtistMetadata; see Common Response Data Elements above


Provisioning

User Package

Contains methods for creating, updating, and authenticating user accounts.

User Package Summary:

Create

Get

IsUsernameAvailable

Login DEPRECATED

SetPassword

Update

User.Create

Description: Creates a user associated with your Partner ID (ApiKey). Returns: User details. Required HTTP Action: POST (see: Tips for Methods That Require a POST Body above) Signature or SSL Required? Both. Implementation Tip: On success, send the user a confirmation email.

Parameters:


In the Query String...






Yes String

In the POST Body...

FirstName The user's first name Yes String

LastName The user's last name Yes String

Username The user's desired username; please see the USER MANAGEMENT USE CASES "Create a User" for important information.

Yes String

Password The user's desired password Yes String

EmailAddress The user's desired email address; please see the USER MANAGEMENT USE CASES "Create a User" for important information.

Yes String

AllowNewsletter The user's preference about whether to receive the MN Open newsletter.

Yes False Boolean

AllowHtmlEmail The user's preference about whether to receive email formatted in HTML or plaintext.

Yes True Boolean




Example in JSON: ?method=user.create&ApiKey=YourApiKey&format=JSON&signature=Signature

Body of POST: {

"User": {

"FirstName": "First",

"LastName": "Last",

"Username": "username",

"Password": "password",

"EmailAddress": "[email protected]",

"AllowNewsletter": "true",

"AllowHtmlEmail": "true",

}

}

Example in XML: ?method=user.create&ApiKey=YourApiKey&format=XML&signature=Signature

Body of POST: <Create xmlns="http://api.mndigital.com">

<User>

<FirstName>First</FirstName>

<LastName>Last</LastName>

<Username>Username</Username>

<Password>password</Password>

<EmailAddress>[email protected]</EmailAddress>

<AllowNewsletter>true</AllowNewsletter>

<AllowHtmlEmail>true</AllowHtmlEmail>

</User>

</Create>

Returns: User; see Common Response Data Elements above

Method-specific Exceptions; see also Common Errors above

Status Code Description Cases 200 Specified

username is already in use

User.Get

Description: Retrieves information about a specific user. Returns: The user's details. Recommended HTTP Action: GET Signature or SSL Required? Neither.

Parameters:




Yes String



Username Username of the specific user Yes String


Example: ?method=user.get&apiKey=YourApiKey&format=json&username=alfred1234

Returns: User; see Common Response Data Elements above

User.IsUsernameAvailable

Description: Checks whether a username is available. (Usernames are unique by customer.) Returns: True/False Recommended HTTP Action: GET Signature or SSL Required? Neither

Parameters:






Username Username to check availability of. Yes String

Example: ?method=user.isUsernameAvailable&username=alfred1234&ApiKey=YourApiKey&format=JSON

Returns: Boolean UsernameIsAvailable; see Common Response Data Elements above

User.Login - DEPRECATED

THIS METHOD IS NO LONGER REQUIRED FOR USE OF THE MN OPEN API. Description: Logs in a user by username and password Returns: an Auth Token (required by other User Package methods) and details about the User. Required HTTP Action: POST (see: Tips for Methods That Require a POST Body above) Signature or SSL Required? Both.

Parameters:



ApiKey Partner's API key. Yes String Method The name of the method to invoke. Yes String Format The format the response should be in,

JSON or XML. No XML String

(Values: XML, JSON)


Yes String

In the POST Body...

Password The user's password. Yes String

Username The user's username. Yes String




Example in JSON: ?method=user.login&ApiKey=YourApiKey&format=JSON&signature=Signature

Body of POST: {

"Username": "Username",

"Password": "password"

}

Example in XML: ?method=user.login&ApiKey=YourApiKey&format=XML&signature=Signature

Body of POST: <Login xmlns="http://api.mndigital.com">

<Username>username</Username>


</Login>

Returns: SessionInfo and User; see Common Response Data Elements above

User.SetPassword

Description: Sets (changes) a user's password. Returns: Confirmation of success or failure. Recommended HTTP Action: GET Signature or SSL Required? Both.

Parameters:



Yes String



New Password The new password for the user.

Yes String

Old Password The original password for the user.

Yes String


Yes String

Username The username for the username whose password is being changed.

Yes String

Example: ?method=User.SetPassword&format=xml&username=alfred123&oldPassword=password1234&newPassword=password5678&apiKey=APIKEY&signature=SIGNATURE

Returns: Success or failure ; see Common Response Data Elements above


User.Update

Description: Updates (changes) information about a specific user. Returns: Success or failure Required HTTP Action: POST (see: Tips for Methods That Require a POST Body above) Signature or SSL Required? Both.

Parameters:







username The user username; returned from a "CreateUser" API call.(Yes in addition to Post Body)

Yes String




Yes String

In the POST Body...

FirstName The user's first name Yes String

LastName The user's last name Yes String

Username The user's desired username; please see the USER MANAGEMENT USE CASES. "Create a User" for important information.

Yes String

Password The user's desired password Yes String

EmailAddress The user's desired email address; please see the USER MANAGEMENT USE CASES. "Create a User" for important information.

Yes String

AllowNewsletter The user's preference about whether to receive the MN Open newsletter.

Yes False Boolean

AllowHtmlEmail The user's preference about whether to receive email formatted in HTML or plaintext.

Yes True Boolean

Example in JSON: ?method=user.update&ApiKey=YourApiKey&format=JSON&username=username&signature=Signature

Body of POST: {

"User": {


"LastName": "Last",

"Username": "username",

"Password": "password",





"AllowNewsletter": "true",

"AllowHtmlEmail": "true",

}

}

Example in XML: ?method=user.update&ApiKey=YourApiKey&format=XML&username=username&signature=Signature

Body of POST: <Update xmlns="http://api.mndigital.com">

<User>



<Username>Username</Username>



<AllowNewsletter>true</AllowNewsletter>


</User>

</Update>

Returns: Success or failure; see Common Response Data Elements above

Cart Package

Contains methods for creating, updating, and purchasing items.

Cart Package Summary:

AddItems

Clear

Get

GetCartByUser

GetDownloadLocations

Purchase

RemoveItems

Cart.AddItems

Description: Adds an item to cart. If no CartId is referenced, a new one is created. Returns: An existing or new CartId, plus a count of items in the cart. Required HTTP Action: POST (see: Tips for Methods That Require a POST Body above) Signature or SSL Required? Signature only.

Parameters:





CartId The Id for the cart that the items will be added to. If empty, a new cart is created.

No Integer


No XML String (Values:


XML, JSON)


Yes String

In the POST Body...

MnetId The MediaNet item identifier for track or album.

Yes String

ItemType The type of item being purchased. Yes String (Values: Track, Album)

Format The codec of the item purchased; MP3 is the only current value supported

Yes String

Price The retail price collected from end-user. Yes Double

The list of items to add to the cart is specified in the POST body, and must be in the same format as specified; i.e., MP3.

Example in JSON: ?method=cart.addItems&CartId=123456&ApiKey=YourApiKey&format=JSON&signature=Signature

Body of POST: (at least one item is required) {

"Items": [

{"MnetId": 12345, "ItemType": "Track", "Format": "MP3", "Price": "0.99"},

{"MnetId": 12347, "ItemType": "Track", "Format": "MP3", "Price": "0.99"},

{"MnetId": 12349, "ItemType": "Album", "Format": "MP3", "Price": "9.99"}

]

}

Example in XML: ?method=cart.addItems&CartId=123456&ApiKey=YourApiKey&format=XML&signature=Signature

Body of POST: <AddItems xmlns="http://api.mndigital.com">

<Items>

<LineItem>


<ItemType>Track</ItemType>

<Format>MP3</Format>

<Price>0.99</Price>

</LineItem>

<LineItem>




<Price>0.99</Price>

</LineItem>

<LineItem>


<ItemType>Album</ItemType>


<Price>9.99</Price>

</LineItem>




</Items>

</AddItems>

Returns: ShoppingCart; see Common Response Data Elements above

Cart.Clear

Description: Clears (empties) an existing CartId (it is not deleted, and may be used again). Returns: Success or failure Recommended HTTP Action: GET Signature or SSL Required? Signature only.

Parameters:




Yes String

CartId The Id for the cart to clear. Yes Integer



Example: ?method=cart.clear&CartId=123456&ApiKey=YourApiKey&format=JSON&signature=Signature

Returns: CartClearResult; see Common Response Data Elements above

Cart.Get

Description: Retrieves the details of a specific cart. Returns: the sub-total, tax, total, and line items including track and album info, and artist and

album art. Recommended HTTP Action: GET Signature or SSL Required? Signature only.

Parameters




CartId The Id for the cart to retrieve. Yes Integer




Yes String

Example: ?method=cart.get&CartId=123456&ApiKey=YourApiKey&format=JSON&signature=Signature





Cart.GetCartByUser

Description: Retrieves a CartId, if any, associated to a user Returns: A CartID, if any, including the line item(s) in it, along with sub-total, tax, and grand total. Recommended HTTP Action: GET Signature or SSL Required? Signature only.

Parameters:




Yes String



State The end-user's state (physical location). Used to calculate tax for cart items. (If state is passed in, tax will be calculated; else not.)

No String

Username The Username of the user in question.

Yes String

Example: ?method=cart.getCartByUser&username=username&ApiKey=YourApiKey&format=JSON&signature=Signature

Returns: UserCartResponse; see Common Response Data Elements above

Cart.GetDownloadLocations

Description: Retrieves the media download locations (URLs) for objects in an OrderID (see Cart.Purchase below)

Returns: Download URLs. Recommended HTTP Action: GET Signature or SSL Required? Signature only.

Parameters:




Yes String

OrderID The identifier for the order. Yes Int




Yes String




Example: ?method=cart.getDownloadLocations&orderId=123456&apiKey=YourApiKey&format=json&signature=Signature

Returns: DownloadLocationsResponse; see Common Response Data Elements above

Cart.Purchase

Description: Purchases a cart using a credit card. Returns: An OrderID to reference by GetDownloadLocations (see above). Recommended HTTP Action: POST (see: Tips for Methods That Require a POST Body above) Signature or SSL Required? Both.

Parameters





CartId The Id for the cart to purchase. Yes Integer




Yes String

UserDomain The domain or host name (site) where the sale originated from.

Yes. String

UserIp The end-user's IP Address. Yes String

In the POST Body...

FirstName The end-user's first name Yes String

LastName The end-user's last name Yes String

EmailAddress The end-user’s email address Yes String

BillingAddress:

AddressLine1 The end-user’s physical address. Yes String

AddressLine2 Additional address line. Yes String

City The end-user’s city. Yes String

State The end-user’s state (2 letter code). Yes String

PostalCode The end-user’s postal code. Yes String

Country The end-user’s country (currently only US is supported).

Yes String

CreditCard:

FirstName First name of credit card holder. Yes String

LastName Last name of credit card holder. Yes String

Number Credit card number (no spaces or dashes). Cards supported are Visa, MC, Amex, and Discover.

Yes String

CVV The credit card security number (also known as CVV2 number).

Yes String




CardType The type of credit card. Values:

Visa

Mastercard, MC

AmericanExpress, Amex

Discover (all case-insensitive)

Yes String

ExpirationMonth The expiration month of card. Yes Int

ExpirationYear The expiration year of card. Yes Int

The user's billing information passed in for processing the purchase must be in the same format as requested for the response (JSON or XML).

Example in JSON: ?method=cart.purchase&CartId=123456&userDomain=www.domain.com&userIp=0.0.0.0&ApiKey=YourApiKey&format=JSON&signature=Signature

Body of POST: {

"FirstName": "John",

"LastName": "Smith",


"BillingAddress": {

"AddressLine1": "2401 Elliott Ave",

"AddressLine2": "Suite 300",

"City": "Seattle",

"State": "WA",

"PostalCode": "98121",

"Country": "US"

},

"CreditCard": {



"Number": "4111111111111111",

"CVV": "258",

"CardType": "Visa",

"ExpirationMonth": "5"

"ExpirationYear": "2009"

},

}

Example in XML: ?method=cart.purchase&CartId=123456&userDomain=www.domain.com&userIp=0.0.0.0&ApiKey=YourApiKey&format=XML&signature=Signature

Body of POST: Note the case of the elements <Purchase xmlns="http://api.mndigital.com">

<User>

<FirstName>John</FirstName>

<LastName>Smith</LastName>


<BillingAddress>

<AddressLine1>2401 Elliott Ave</AddressLine1>

<AddressLine2>Suite 300</AddressLine2>

<City>Seattle</City>

<State>WA</State>

<PostalCode>98121</PostalCode>


<Country>US</Country>

</BillingAddress>

<CreditCard>



<Number>4111111111111111</Number>

<CVV>258</CVV>

<CardType>Visa</CardType>

<ExpirationMonth>5</ExpirationMonth>

<ExpirationYear>2009</ExpirationYear>

</CreditCard>

</User>

</Purchase>

Returns: Order [] Orders; see Common Response Data Elements above

Cart.RemoveItems

Description: Removes one or more item(s) from an existing cart. Returns: The remaining count (zero or more) in the CartID. Required HTTP Action: POST (see: Tips for Methods That Require a POST Body above) Signature or SSL Required? Signature only.

Parameters:





CartId The Id for the cart that the items will be removed from.

Yes Integer




Yes String

In the POST Body...


Yes String


Format The codec of the item purchased; MP3 is the only current value supported

Yes String

The list of items to remove from the cart is specified in the POST body, and must be in the same format as specified in the query string; i.e., XML vs. JSON.

Example in JSON: ?method=cart.removeItems&CartId=123456&ApiKey=YourApiKey&format=JSON&signature=Signature




Body of POST: {

"Items": [

{"MnetId": 12345, "ItemType": "Track", "Format": "MP3" },

{"MnetId": 12347, "ItemType": "Track", "Format": "MP3" }

]

}

Example in XML: ?method=cart.removeItems&CartId=123456&ApiKey=YourApiKey&format=XML&signature=Signature

Body of POST: <RemoveItems xmlns="http://api.mndigital.com">

<Items>

<LineItem>




</LineItem>

<LineItem>




</LineItem>

</Items>

</RemoveItems>


Purchase Package

Contains methods for purchasing outside a shopping cart paradigm.

Purchase Package Summary:

UseBalance

UseCreditCard

Purchase.UseBalance

Description: Purchases a single or multiple tracks and/or albums, debiting your Account Balance. Please note that account balances must always be positive.

Returns: An OrderID and download media locations Required HTTP Action: POST (see: Tips for Methods That Require a POST Body above) Signature or SSL Required? Both.

Parameters:










Yes String

SiteDomain The host name (site) where the sale originated from.

Yes String

UserIP The IP Address of the end user making the purchase.

Yes String

Username Optional: The username of end-user to associate order with (must pass in a valid username that has previously been created). See asterisk-marked items immediately next.

No String

In the POST Body...

User*

FirstName The end-user's first name Yes* String

LastName The end-user's last name Yes* String

EmailAddress The end-user’s email address Yes* String

BillingAddress:

Address1 The end-user’s physical address. Yes* String

Address2 Additional address line. Yes* String

City The end-user’s city. Yes* String

State The end-user’s state (two-letter code). Yes* String

PostalCode The end-user’s postal code. Yes* String


Yes* String

Items


Yes String


Format The (asset) format of the item being purchased

Yes String (Values: MP3)

Price The retail price collected from end-user. For Sony and UMG content Price must be the required retail price (Sony and UMG are the two Labels where IsSetPrice=true). For all other content Price must be the wholesale price of the asset.

Yes Double

Tax The amount of tax collected from end-user for the item. If no tax was charged, use 0.00. For Sony content sold to residents of Texas tax must be 8.25% of the required retail price. For all other content (or Sony content sold to residents of any other state) it will be 0.00

Yes Double

TotalCharge The total amount to be deducted from Partner account. This equals the sum of whatever values appear in Price + Tax fileds above

Yes Double



* Only required if: (1) valid Username is not passed in or (2) data for user that needs to be updated.

* For all transactions and regardless of the value entered in the <price> field above, the customer account balance (which is viewable using Partner.GetBalance) will reflect the wholesale price of item(s) deducted, as well as the tax charged (for transactions of Sony content to residents of TX).

Example in JSON: ?method=purchase.usebalance&apiKey=YourApiKey&format=json&userIP=enduserIPAddress&siteDomain=domainname&signature=Signature

Body of POST: {

"User": // Not required if Username parameter used (for existing user)

{




"BillingAddress": {



"City": "Seattle",

"State": "WA",


"Country": "US"

},

"Items": [

{"MnetID":12345,"ItemType":"Track","Format":"MP3","Price":0.99,"Tax":0.00}


{"MnetID":12349,"ItemType":"Album","Format":"MP3","Price":9.99,"Tax":0.00}

],

"TotalCharge": 8.43 // The amount to be deducted from Customer(Partner)

account (PartnerCost (wholesale price) +

UserChargedTax)

}

Example in XML: ?method=purchase.usebalance&apiKey=YourApiKey& format=XML&userIP=enduserIPAddress&siteDomain=domainname&signature=Signature

Body of POST: Note the case of the elements <UseBalance xmlns="http://api.mndigital.com">

<User>

 <FirstName>John</FirstName>



<BillingAddress>




<State>WA</State>



</BillingAddress>

</User>

<Items>

<LineItem>




<Price>0.99</Price>

<Tax>0.00</Tax>

</LineItem>

<LineItem>




<Price>0.99</Price>

<Tax>0.05</Tax>

</LineItem>

<LineItem>




<Price>9.99</Price>

<Tax>0.00</Tax>

</LineItem>

</Items>

<TotalCharge>8.43</TotalCharge>

<!-- The amount to be deducted from Customer (Partner) account (PartnerCost (wholesale price) + UserChargedTax) --

>

</UseBalance>

Returns: PurchaseUseBalanceResults; see Common Response Data Elements above

Purchase.UseCreditCard

Description: Purchases a single or multiple tracks and/or albums, using a credit card. Returns: An OrderID to reference by Cart.GetDownloadLocations (see above) Required HTTP Action: POST (see: Tips for Methods That Require a POST Body above) Signature or SSL Required? Both.

Parameters:








Yes String

SiteDomain The host name (site) where the sale originated from.

Yes String

UserIP The IP Address of the end user making the purchase.

Yes String

Username The username of end-user to associate order with (must pass in a valid username that has previously been created).

No String

In the POST Body...

User*

FirstName The end-user's first name Yes* String

LastName The end-user's last name Yes* String

EmailAddress The end-user’s email address Yes* String



BillingAddress:

AddressLine1 The end-user’s physical address. Yes* String

AddressLine2 Additional address line. Yes* String

City The end-user’s city. Yes* String

State The end-user’s state (2 letter code). Yes* String

PostalCode The end-user’s postal code. Yes* String


Yes* String

CreditCard

FirstName First name of credit card holder. Yes** String

LastName Last name of credit card holder. Yes** String


Yes** String


Yes** String


Visa

Mastercard, MC



Yes** String

ExpirationMonth The expiration month of card. Yes** Int

ExpirationYear The expiration year of card. Yes** Int

Items:


Yes String


Format The (asset) format of the item being purchased

Yes String (Values: MP3)

Price The retail price collected from end-user. Yes Double

Tax The amount of tax collected from end-user for the item. If no tax was charged, use 0.00.

Yes Double

TotalCharge The total amount collected from end-user. This must match the amount of all the line items added up.

Yes Double

* Only required if: (1) valid Username is not passed in or (2) data for user needs to be updated. ** Only required if (1) valid Username is not passed in or (2) user does not have a credit card on file.

When calling Purchase.UseCreditCard, if supplying the User object, both CreditCard and BillingAddress must be passed in. These parameters do not default to the user information which may or may not be on file

Example in JSON: ?method=purchase.usecreditcard&apiKey=YourApiKey& format=json&userIP=enduserIPAddress&siteDomain=domainname&signature=Signature

Body of POST: {

"User": // Not required if Username parameter used (for existing user)

{




"BillingAddress": {



"City": "Seattle",

"State": "WA",


"Country": "US"

},

"CreditCard": {



"Number": "4111111111111111",

"CVV": "258",

"CardType": "Visa",

"ExpirationMonth": "5"

"ExpirationYear": "2010"

},

"Items": [



{"MnetID":12349,"ItemType":"Album","Format":"MP3","Price":9.99,"Tax":0.00}

],

"TotalCharge": 12.02 // total to be charged to user's credit card

}

Example in XML: ?method=purchase.usecreditcard&apiKey=YourApiKey& format=XML&userIP=enduserIPAddress&siteDomain=domainname&signature=Signature

Body of POST: Note the case of the elements <UseCreditCard xmlns="http://api.mndigital.com">

<User>

 <FirstName>John</FirstName>



<BillingAddress>




<State>WA</State>



</BillingAddress >

<CreditCard>



<Number>4111111111111111</Number>

<CVV>258</CVV>




</CreditCard>

</User>

<Items>

<LineItem>




<Price>0.99</Price>

<Tax>0.00</Tax>

</LineItem>

<LineItem>




<Price>0.99</Price>

<Tax>0.05</Tax>

</LineItem>

<LineItem>




<Price>9.99</Price>

<Tax>0.00</Tax>

</LineItem>

</Items>

<TotalCharge>12.02</TotalCharge>



</UseCreditCard>

Returns: PurchaseUseCreditCardResults; see Common Response Data Elements above


Management

Partner Package

Contains methods for managing your account balance.

Summary:

GetAMGData

GetBalance

RefillBalance

Partner.GetAMGData

Description: Retrieves AMG biography for an artist and/or AMG review for an album Returns: AMG data for the album or the artist in the form of AMGDataResults. Recommended HTTP Action: GET Signature or SSL Required? Signature only. -- See Notes below

Parameters:



Yes String

artistMnetId Artist Id used for biography for artist.

No* String

albumMnetId Album Id used for review for album.

No* String




Yes String

*At least one of the two parameters, artistMnetId and or albumMnetId must be specified. If you specify an artistMnetId, artist biography is returned. If an albumMnetId is specified, album review biography is returned. If both are specified, both artist biography and album review are returned.

Example: ?method=partner.getAMGData&artistMnetId=ARTISTID&albumMnetId=ALBUMID&apiKey=YourApiKey&signature=Signature

Returns: AMGDataResults

Notes: Authorization (configuration) is required in order to use this API; please contact ApiSupport to make changes. If authorization is not obtained, the call returns the error message “Not authorized, you do not have rights to run this command.”

The response includes a Google Analytics (JavaScript) snippet; specifically, each of a bio and/or a review is returned with the snippet as part of the data blob. You must consume or pass through




the blob fully intact into your application or site(s), including both the AMG attribution and the Google Analytics snippet, even if that means the snippet will appear multiple times on a page.

Partner.GetBalance

Description: Retrieves your current account balance Returns: Available balance. Recommended HTTP Action: GET Signature or SSL Required? Signature only.

Parameters:




Yes String




Yes String

Example: ?method=partner.getBalance&apiKey=YourApiKey&signature=Signature

Returns: PartnerGetBalanceResults; see Common Response Data Elements above

Partner.RefillBalance

Description: Refills (or adds to) your account balance. Please note that we charge a 3% processing fee for credit card refills.

Returns: Success or failure Recommended HTTP Action: POST (Tips for Methods That Require a POST Body above) Signature or SSL Required? Signature only.

Parameters:




Yes String

Amount Dollar amount to refill account with

Yes Double




Yes String

Creditcard: note when using XML that the second "c" is lowercase

FirstName First name of credit card holder.

Yes String

LastName Last name of credit card holder.

Yes String








Yes String


Yes String


Visa

Mastercard, MC



Yes String

ExpirationMonth The expiration month of card. Yes Int

ExpirationYear The expiration year of card. Yes Int

Address: note that this *is* just "Address" not "BillingAddress"

AddressLine1 The end-user’s physical address.

Yes String

AddressLine2 Additional address line. Yes String

City The end-user’s city. Yes String

State The end-user’s state (2 letter code).

Yes String

PostalCode The end-user’s postal code. Yes String


Yes String

Example in JSON: ?method=partner.refillBalance&apiKey=YourApiKey&format=json&Amount=100.00&signature=Signature

Body of POST: {

"Creditcard": {


"LastName": "Last",

"Number": "4111111111111111",

"CVV": "000",

"CardType": "Visa",

"ExpirationMonth": "5",

"ExpirationYear": "2009",

"Address": {

"AddressLine1": "2401 Elliott Ave.",


"City": "Seattle",

"State": "WA",


"Country": "US"

}

}

}


Example in XML: ?method=partner.refillBalance&apiKey=YourApiKey&format=xml&Amount=100.00&signature=Signature

<RefillBalance xmlns="http://api.mndigital.com">

<Creditcard>



<Number>4111111111111111</Number>

<CVV>000</CVV>




<Address>

<AddressLine1>2401 Elliott Ave.</AddressLine1>



<State>WA</State>



</Address>

</Creditcard>

</RefillBalance>

Returns: PartnerRefillBalanceResults; see Common Response Data Elements above

Report Package

Contains methods for generating reports.

Summary:

GetOrderHistory

Report.GetOrderHistory

Description: Retrieves orders by end user username within a range of "start" and "end" dates Returns: Order history and information. Recommended HTTP Action: GET Signature or SSL Required? Signature only.

Parameters:




Yes String

Ascending Sort direction. No Ascending Boolean

EndDate The ending date to return order history for.

Yes String



pageNumber The page number that should be retrieved.

No 1 Int

recordsToReturn The number of items per page. No 5 Int




Yes String

SortType Field to sort the report by. Options include:

FirstName

LastName

OrderID

OrderDate

OrderStatus

PaymentAmount

PaymentStatus

No Orderdate String

StartDate The starting date to return order history for.

Yes String

Username* The user to get order history for.

Yes* String

*If a username is passed in, the order history for that user is returned. If no username, the order history for the customer (determined by ApiKey) is returned.

Example: ?method=report.getOrderHistory&apiKey=YourApiKey&page=1&pageSize=10&Username=Username&startDate=1/1/09&endDate=4/1/09& sortType=orderdate&ascending=true&signature

Returns: Order history report; see Common Response Data Elements above

Possible values for OrderStatus and PaymentStatus:

OrderStatus Explanation

New Order is created

Order Processing Order is awaiting payment creation

Payment Pending Order is placed and pending payment

Successful Order successfully completed

Failed Order failed

Refunded Order refunded

PaymentStatus Explanation

Payment Inserted Payment record Inserted

New Payment record created

Pending Payment sent to processor

Pre-Auth Successful Pre-Auth Successful

Pre-Auth Failed Pre-Auth Failed

Post-Auth Sucessful Post-Auth Successful

Post-Auth Failed Post-Auth Failed

Refunded Payment Refunded

Use Cases

The following section details the recommended sequences of steps to accomplish tasks via the MN Open API:




Search Management o Find artists o Find albums o Get album and tracks

Cart Management o Core Use Case: purchase and download tracks o Create a cart / Add Items to a cart o Clear (empty) an existing cart o Remove an item from an existing cart o View/Display Cart Details o Purchase a cart (using a credit card) o Retrieve download locations for a user to download content

User Management o Create User o View/Display User Details o Set (change) a User's Password o Update (change) a User's Details

The following API calls supporting the use cases are described in more detail below, including typical

request URI and XML response.

Typical API calls including request and responses The following section includes typical API calls including associated request and responses. For actual details of the parameters in the request URI, please refer to the API calls above. The responses are subject to minor changes and are included here for illustrative purposes.

SEARCH MANAGEMENET USE CASES

API Calls detailed in this section:

Search.GetArtists

Search.GetAlbums

Search.GetTracks

Album.GetTracks

Artist.GetAlbums


Search.GetArtists

Typical request API Call: Search.GetArtists: http://ie-

api.mndigital.com?method=Search.GetArtists&format=xml&name=&keyword=&page=1&pageSize=10&apiKey=Yourapikey

Sample screen shot of results/response.

Typical response: Search.GetArtists

<?xml version="1.0" encoding="utf-8"?>

- <ArtistSearchResults xmlns="http://api.mndigital.com"




- <Artists>

- <Artist>


<Name>New Philharmonia Orchestra, The</Name>

- <Images> <Artist180x80>http://images.musicnet.com/artists/000/487/975/b.jpeg</Artist180x80>




</Images>

</Artist>

- <Artist>


<Name>!!!</Name>

- <Images>






</Images>

</Artist>

- <Artist>


<Name>!Akimbo</Name>





</Images>

</Artist>

- <Artist>


<Name>!Deladap</Name>





</Images>

</Artist>

- <Artist>


<Name>!JP</Name>





</Images>

</Artist>

- <Artist>


<Name>!T.O.O.H.!</Name>





</Images>

</Artist>

- <Artist>


<Name>!Tang</Name>





</Images>

</Artist>

- <Artist>


<Name>"22 Novembre" Band</Name>





</Images>

</Artist>

- <Artist>


<Name>"Annigma" Ensemble, The</Name>






</Images>

</Artist>

- <Artist>


<Name>"Beans" hambone</Name>





</Images>

</Artist>

</Artists>

</ArtistSearchResults>


Search.GetAlbums

Typical Request: http://ie-api.mndigital.com?method=Search.GetAlbums&format=xml&title=&artist=sting&artistMnetId=&rights=purchase&keyword=&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=Yourapikey


http://ie-api.mndigital.com/?method=Search.GetAlbums&format=xml&title=&artist=sting&artistMnetId=&rights=purchase&keyword=&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=Yourapikey




Typical Response: - <AlbumSearchResults xmlns="http://api.mndigital.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">



- <Albums>

- <Album>


<Title>Fields Of Gold: The Best Of Sting 1984-1994</Title>

- <Artist>


<Name>Sting</Name>





</Images>

</Artist>

<Genre>Pop</Genre>


<Label>A&M</Label>




- <Images> <Album75x75>http://images.musicnet.com/albums/000/540/993/s.jpeg</Album75x75>



</Images>


- <Tracks>

- <Track>


<Title>When We Dance</Title>

- <Artist>


<Name>Sting</Name>




<Artist200x>http://images.musicnet.com/artists/000/031/068/f.jpeg</Artist200x> </Images>

</Artist>

<Genre>Pop</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>

<Location>rtmp://DMUS.flash-

ie.musicnet.com:80/Sample</Location>


</MediaLocation>

</SampleLocations>


<PopularityRanking>45652</PopularityRanking>

</Track>

- <Track>

.........................

</Track>

- <Track>

.........................


</Track>

- <Track>

.........................

</Track>

</Tracks>


- <PriceTag>



<IsSetPrice>true</IsSetPrice>


</PriceTag>


</Album>

<Album>

...........................

</Album>

<Album>

...........................

</Album>

</Albums>

</AlbumSearchResults>


Search.GetTracks

Typical Request: http://ie-api.mndigital.com?method=Search.GetTracks&format=xml&title=Fields%20of%20Gold&album=&albumMnetId=&artist=&artistMnetId=&keyword=&rights=purchase&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&blacklistIds=&apiKey=Yourapikey


Typical Response: - <TrackSearchResults xmlns="http://api.mndigital.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">



- <Tracks>

- <Track>


<Title>Fields Of Gold</Title>

- <Artist>


<Name>Sting</Name>






</Images>

</Artist>

<Genre>Pop</Genre>






- <PriceTag>





</PriceTag>

- <Mp3Rights>




</Mp3Rights>


- <Album>



<Artist i:nil="true" />

<Genre>Pop</Genre>


<Label>A&M</Label>







</Images>




</Album>

- <SampleLocations>

- <MediaLocation>




</MediaLocation>

</SampleLocations>



</Track>

- <Track>

......................

</Track>

- <Track>

......................

</Track>

</Tracks>

</TrackSearchResults>


Album.GetTracks

Typical Request: http://ie-api.mndigital.com?method=Album.GetTracks&format=xml&mnetId=540993&blacklistIds=&apiKey=Yourapikey


Typical Response:- <AlbumMetadata xmlns="http://api.mndigital.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">


- <Album>



- <Artist>


<Name>Sting</Name>





http://ie-api.mndigital.com/?method=Album.GetTracks&format=xml&mnetId=540993&blacklistIds=&apiKey=Yourapikey&timestamp=1254176985&signature=22e9bf6cc8d72dc7f80be024cb031671




</Images>

</Artist>

<Genre>Pop</Genre>


<Label>A&M</Label>







</Images>


- <Tracks>

- <Track>


<Title>When We Dance</Title>

- <Artist>


<Name>Sting</Name>





</Images>

</Artist>

<Genre>Pop</Genre>






- <PriceTag>





</PriceTag>

- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>




</MediaLocation>

</SampleLocations>



</Track>

- <Track>

..............................

</Track>

</Tracks>


- <PriceTag>





</PriceTag>


</Album>

</AlbumMetadata>


Artist.GetAlbums

Typical Request: http://ie-api.mndigital.com?method=Artist.GetAlbums&format=xml&mnetId=31068&rights=sample&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&blacklistIds=&apiKey=Yourapikey



Typical Response: - <ArtistMetadata xmlns="http://api.mndigital.com" xmlns:i="http://www.w3.org/2001/XMLSchema-

instance">


- <Artist>


<Name>Sting</Name>





</Images>

</Artist>

<TotalAlbums>31</TotalAlbums>

- <Albums>

- <Album>



- <Artist>


<Name>Sting</Name>





</Images>

</Artist>

<Genre>Pop</Genre>


<Label>A&M</Label>




+ <Images> <Album75x75>http://images.musicnet.com/albums/000/540/993/s.jpeg</Album75x75>



</Images>



- <PriceTag>





</PriceTag>


</Album>

- <Album>

.............................

</Album>

- <Album>

.............................

</Album>

- <Album>

.............................

</Album>

- <Album>

.............................

</Album>

</Albums>

</ArtistMetadata>


CART MANAGEMENT USE CASES

Carts do not expire, whether empty or non-empty. This may change in the future. A particular user may have only one cart associated with their identifier; see Cart.GetCartByUser.

Core Use Case: to purchase and download tracks (see following use cases for details): 1. Cart.AddItems 2. Optional: Cart.Get 3. Cart.Purchase 4. Cart.GetDownloadLocations

Create a cart / Add Items to a cart 1. Call Cart.AddItems with one or more MNetIDs

Note: If no CartId is included as an input parameter, a new cart is created

2. On Success, the new or existing CartId is returned, along with the current Count of items in the cart.

Clear (empty) an existing cart 1. Prerequisites:

1. The cart (CartId) must exist and be non-empty 2. Call Cart.Clear with the CartId to be cleared 3. On Success, the CartId will be returned, along with the current Count (zero items)

Remove an item from an existing cart 1. Prerequisites:

1. The cart (CartId) must exist and be non-empty Best Practice: call Cart.Get first to verify its contents and display to the end user

2. Call Cart.RemoveItems with the CartId and single item to be removed (by MNetID) 3. On Success, the CartId will be returned, along with the current Count (reduced by one) 4. Best Practice: call Cart.Get to display the reduced cart details to the user

View/Display Cart Details 1. Prerequisites:

1. The cart must exist; if appropriate, call Cart.AddItems (see above) 2. Call Cart.Get with CartId 3. On Success, the details of the specified cart are returned, including sub-total, tax, total, and line

items including track and album info, and artist and album art

Retrieve a cart associated with a user 1. Prerequisites:

1. The UserID must exist; if appropriate, call User.Create (see below) 2. Call Cart.GetCartByUser with the specified UserID 3. On Success, the CartId, if any, is returned (use Cart.Get to display its contents).

Purchase a cart (using a credit card) 1. Prerequisites:

1. The cart (CartId) must exist and be non-empty 2. Best Practice: call Cart.Get first to verify its contents and display to the end user 3. Call Cart.Purchase with the specific CartId and credit card details

Note: the majority of the required details go into the POST body section


4. On Success, the cart becomes an "order" and an OrderID is returned, to reference subsequently by GetDownLoad locations

Retrieve download locations for a user to download content 1. Prerequisites:

1. A non-empty CartId must have been first purchased and converted to an Order (OrderID) 2. Call Cart.GetDownloadLocations with the desired OrderID (obtained from Cart.Purchase, above) 3. On Success, one or more URL-encoded Download Location(s) will be returned. Be sure to handle

the encoding properly when displaying download locations to a user. (The "&" must become simply an "&".)


Cart.AddItems

Cart.Get

Cart.Purchase




Cart.AddItems

Typical Request: https://ie-

api.mndigital.com?method=Cart.AddItems&format=xml&cartId=&apiKey=Yourapikey

Typical Response: <?xml version="1.0" encoding="utf-8"?> <CartItemCount xmlns="http://api.mndigital.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-

instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">


<CartId>38626</CartId>

<Count>1</Count>

<Status>

<DuplicateItemInCart>false</DuplicateItemInCart>

<CartAlbumContainsTrack>false</CartAlbumContainsTrack>

<CartTrackInAlbum>false</CartTrackInAlbum>

</Status>

</CartItemCount>

https://ie-api.mndigital.com/?method=Cart.AddItems&format=xml&cartId=&apiKey=Yourapikey

https://ie-api.mndigital.com/?method=Cart.AddItems&format=xml&cartId=&apiKey=Yourapikey


Cart.Get

Typical Request: http://ie-api.mndigital.com?method=Cart.Get&format=xml&cartId=38626&apiKey=Yourapikey

Typical Response: - <ShoppingCart xmlns="http://api.mndigital.com" xmlns:i="http://www.w3.org/2001/XMLSchema-

instance">



<SubTotal>0.99</SubTotal>

<Tax>0.0</Tax>

<Total>0.99</Total>

- <Items>

- <LineItem>



<Price>0.99</Price>

- <Description>

<TrackMnetId>12296213</TrackMnetId>

<TrackTitle>Karaoke: Spin The Black Circle</TrackTitle>

<ArtistMnetId>43089</ArtistMnetId>

<ArtistName>Pearl Jam</ArtistName>

<AlbumMnetId>12296211</AlbumMnetId>

<AlbumTitle>Karaoke Tribute: More Tribute To Pearl Jam</AlbumTitle>

<AlbumLabel>APM Music</AlbumLabel>








</Images>

<AlbumLabelOwnerId>122</AlbumLabelOwnerId>

<TrackDiscNumber>1</TrackDiscNumber>


</Description>


</LineItem>

</Items>

</ShoppingCart>

http://ie-api.mndigital.com/?method=Cart.Get&format=xml&cartId=38626&apiKey=Yourapikey


Cart.Purchase

Typical Request: https://ie-api.mndigital.com?method=Cart.Purchase&format=xml&cartId=38626&userIp=0.0.0.0&userDomain=testdomain.mndigital.com&apiKey=Yourapikey

Typical Response: <Order xmlns="http://api.mndigital.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">


<ID>325447</ID>

<Date>09-28-2009</Date>

<Time>15:53</Time>

<SubTotal>0.99</SubTotal>

<Tax>0.09</Tax>

<Total>1.08</Total>

<Items>

<LineItem>



<Price>0.99</Price>


<Description>


<TrackTitle>Karaoke: Spin The Black Circle</TrackTitle>




<AlbumTitle>Karaoke Tribute: More Tribute To Pearl Jam</AlbumTitle>


<Images> <Album75x75>http://images.musicnet.com/albums/012/296/211/s.jpeg</Album75x75>







</Images>


<TrackDiscNumber>1</TrackDiscNumber>


</Description>

<DownloadLocations>

<MediaLocation>


<Location>http://DMUS.download-

ie.musicnet.com/sample/download/location/</Location>

</MediaLocation>

</DownloadLocations>

<AssetCode>MP3_DOWNLOAD_UENC_320kb_070</AssetCode>

</LineItem>

</Items>

<User>

<ID>ea34e758-22e0-44d3-856d-bf2243099118</ID>




<PartnerPID>211-22-8704</PartnerPID>

<AllowNewsletter>false</AllowNewsletter>


<BillingAddress>

<AddressLine1>2401 Elliott Ave.</AddressLine1>



<State>Washington</State>


https://ie-api.mndigital.com/?method=Cart.Purchase&format=xml&cartId=38626&userIp=0.0.0.0&userDomain=testdomain.mndigital.com&apiKey=Yourapikey





</BillingAddress>

<CreditCard>



<Number>1111</Number>




<CardID>0</CardID>

</CreditCard>

</User>

<OrderStatus>Successful</OrderStatus>

</Order>



Typical Request: http://ie-api.mndigital.com?method=Cart.GetDownloadLocations&format=xml&orderId=325447&customerId=testdomain.mndigital.com&apiKey=Yourapikey

Typical Response: - <DownloadLocationResults xmlns="http://api.mndigital.com"




- <DownloadLocations>

- <MediaLocation>


<Location>http://DMUS.download-

ie.musicnet.com/sample/download/location/</Location>

<Resource i:nil="true" />

</MediaLocation>

</DownloadLocations>

</DownloadLocationResults>

http://ie-api.mndigital.com/?method=Cart.GetDownloadLocations&format=xml&orderId=325447&customerId=testdomain.mndigital.com&apiKey=Yourapikey



http://dmus.download-/



Typical Request: http://ie-api.mndigital.com?method=Report.GetOrderHistory&format=xml&username=&startDate=1%2F1%2F2000&endDate=1%2F1%2F2020&pageNumber=1&recordsToReturn=10&sortType=&ascending=true&apiKey=Yourapikey

Typical Response: - <OrderResults xmlns="http://api.mndigital.com" xmlns:i="http://www.w3.org/2001/XMLSchema-

instance">



- <Orders>

- <Order>

<ID>24723</ID>

<Date>05-14-2009</Date>

<Time>15:24</Time>

<SubTotal>5</SubTotal>

<Tax>5</Tax>

<Total>10</Total>

- <Items>

- <LineItem>



<Price>5</Price>

- <Description>


<TrackTitle>Karaoke: Spin The Black

Circle</TrackTitle>




<AlbumTitle>Karaoke Tribute: More Tribute To Pearl

Jam</AlbumTitle>









</Images>


<TrackDiscNumber i:nil="true" />

<TrackNumber i:nil="true" />

</Description>


</LineItem>

</Items>

- <User>

<ID>6979f93d-5b14-4103-a1ab-62eb3fc06c45</ID>

<FirstName i:nil="true" />

<LastName i:nil="true" />

<Username i:nil="true" />

<EmailAddress i:nil="true" />

<PartnerPID i:nil="true" />


<AllowHtmlEmail>false</AllowHtmlEmail>

</User>

<OrderStatus>Successful</OrderStatus>

<PaymentStatus i:nil="true" />

</Order>

</Orders>

</OrderResults>


USER MANAGEMENT USE CASES

We expect that you will maintain or mirror user data within your own application. MediaNet will not edit or purge customer data in IE or PROD.

Create User Usernames must be unique with the scope of a customer -- as represented by customer API key. (We assume they are unique in the customer's system/website.)

Tip: Username and email address may be the same or different. Making them the same is simpler, but precludes letting user's change their email address at a later time. Making them different enables users to change email addresses independently of Username.

1. Best Practice: call User.IsUsernameAvailable with the user's desired Username/email address 1. If Username and email address are the same, call User.IsUsernameAvailable with the

user's desired email address 2. If Username and email address are different, call User.IsUsernameAvailable with the

user's desired Username 2. Call User.Create with Firstname, Lastname, Username, email address, and password. 3. On success the user's details will be returned in the response.

View/Display User Details 1. Prerequisites:

1. The user must exist; it not, call User.Create (see above) 2. Call User.Get with username in question 3. On Success, all of the user's details are returned

Set (change) a User's Password 1. Prerequisites:

1. The user must exist; it not, call User.Create (see above) 2. Call User.SetPassword with the username in question, and the old and new passwords 3. On Success, a confirmation is returned.

Update (change) a User's Details 1. Prerequisites:

1. The user must exist; it not, call User.Create (see above) 2. Call User.Update with, at minimum, the username and at least one other item to be changed.

Tip: Username parameter must be on the URL as well.



User.Create

User.Update

User.Create

Typical Request: https://ie-api.mndigital.com?method=User.Create&format=xml&apiKey=Yourapikey&timestamp=1254178777&domain=yourDomain.com

Typical Response: <CreateUserResponse xmlns="http://api.mndigital.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-



<User>

<ID>8f6951a7-02ac-43f3-84ae-76fce76a2c9e</ID>

<FirstName>EndUserFirstName</FirstName>

<LastName>EndUserlastName</LastName>

<Username>EndUserUsername</Username>

<Password>EndUserpassword</Password>



<Role/>

<Association/>



</User>

</CreateUserResponse>

https://ie-api.mndigital.com/?method=User.Create&format=xml&apiKey=Yourapikey&timestamp=1254178777&domain=yourDomain.com




User.Update

Typical Request: http://ie-

api.mndigital.com?method=User.Update&format=xml&username=username&apiKey=Your

APIKey&signature=signature

Typical Response: <CreateUserResponse xmlns="http://api.mndigital.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-



<User>

<ID>8f6951a7-02ac-43f3-84ae-76fce76a2c9e</ID>

<FirstName>EndUserFirstName</FirstName>

<LastName>EndUserlastName</LastName>

<Username>EndUserUsername</Username>

<Password>EndUserpassword</Password>



<Role/>

<Association/>



</User>

</CreateUserResponse>


Appendix A: Sony Agency Model Nexuses and Tax Rates

The Sony Agency Model dictates that for Sony content, Sony Corporation is the seller of record, and MediaNet and its customers are its "agents." Tax must be collected for users whose Billing Address is located in the following states, at the corresponding rates:

Texas: 8.25%


Appendix B: Label Owners by Identifier and Name

You can use the Label.GetLabelOwners API call to get a current list of Label owners. http://ie-api.mndigital.com?method=Label.GetLabelOwners&format=xml&apiKey=yourapikey Returne results:

- <LabelOwnerResults xmlns="http://api.mndigital.com"




- <LabelOwners>

- <LabelOwner>

<LabelOwnerID>395</LabelOwnerID>

<LabelOwnerName>!K7 Records</LabelOwnerName>

</LabelOwner>

- <LabelOwner>

<LabelOwnerID>149</LabelOwnerID>

<LabelOwnerName>1201 Music</LabelOwnerName>

</LabelOwner>

………………………………. ……………………………….. ………………………………………

</LabelOwners>

</LabelOwnerResults>



Appendix C: Sample Code

PHP Sample Code of the MNOpen API call to search for an artist’s albums and tracks The following code uses MediaNet’s MNOpen API (Search, namely Search.GetAlbums API call) to look for all albums and tracks by an artist, in this example, for all albums and tracks by “Sting”.

The code is written in PHP. At the core of this code is a call to Search.GetAlbums. For additional information on Search.GetAlbums API call, please see the MNOpen API documents. The PHP code (contained in index.php) wraps the Search.GetAlbums API call in and does a HTTP call to the MNOpen web site to obtain an XML response of all the albums and tracks for an artist, in this case sting. A curl_exec function call is the center of the PHP code. For a full listing see PHP listing below. There are two environments that you can make your call to.

An Integration Environment (IE) is used for development and testing.

Clearly, you may not want to execute real transactions, such as a real credit card

purchase of an album or a track, through the Production Environment, during your

development and testing phase.

Simply modify http://ie-api.mndigital.com to http://api.mndigital.com, in order to switch

from Integration to Production environment, when final testing is completed.

$theQuery parameter contains the Search.GetAlbums API call and its parameters format=xml&artist=sting&rights=purchase&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=APIKey.

format=xml specifies to return XML from the call.

artist=sting specifies to return results for artist Sting.

rights=purchase specifies to return results for albums and tracks which can be sold.

mainArtistOnly=true specifies to return results for albums and tracks where Sting is the

main artist, not a tribute band or other artist performing a sting song.

page=1&pageSize=10 specify how much results to return per call to protect your buffer,

but fill your display area. These parameters are used for paging. You can leave them out

and get all the results in one shot.

apiKey=APIKey specifies “your entity” uniquely, and thus is perhaps the most important

and most common API parameter. You may want to store this in a safe file and build it

into every API call

All we have to do now is post the HTTP query and parse the XML results. We then take the xml returned into a for-each-loop, which operates on all nodes in the XML returned. You can of course load this into your favorite XML DOM and XPath it, or iterate over the nodes as you like, in any way you like.


Full listing of the Index.php HTML page, the output, and the XML returned from the MNOpen API call, is included below for completeness.


Screen of Index.php


Full HTML of Index.php <html>

<head>

</head>

<body>

Searching for artist "sting" for all Albums and all tracks.

<br /><br />

<?php

// Initialize the query parameters for search

// Ideally, buils this query in a more general fashion,

// depending on the API call you like to make

// and the parameters specific to the API call

$theQuery =

"method=Search.GetAlbums&format=xml&artist=sting&rights=purchase&includeExplicit=true&mainArtistO

nly=true&page=1&pageSize=10&apiKey= APIKey";

// This is standard curl call of PHP

$curl = curl_init();

curl_setopt ($curl, CURLOPT_URL, "http://ie-

api.mndigital.com?".$theQuery."&rpp=10");

curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec ($curl);

curl_close ($curl);

// Now that we have the XML response,

// let's load it and find the titles for albums and tracks

$domDoc = new DOMDocument();; ;

$dom = $domDoc->loadXML($response);

// this should not happen

if (!$dom) {

echo "Error while parsing the response\n";

exit;

}

// We have a valid XML doc loaded

$Albums = $domDoc->getElementsByTagName('Album'); // Find All Album and Track titles

for ($i = 0; $i < $Albums->length; $i++) {

$Titles = $Albums->item($i)->getElementsByTagName('Title'); // Find All Album and

Track titles

echo "Album: ".$Albums->item($i)->getElementsByTagName('Title')->item(0)-

>nodeValue. "<br />";

for ($j = 1; $j < $Titles->length; $j++) {

echo " Track: " . $Titles->item($j)->nodeValue . "<br

/>";

}

echo "<br />";

}

?>

</body>

</html>


Output from Index.php Searching for artist "sting" for all Albums and all tracks.

Album: The Very Best Of Sting And The Police (2002 Brits Version) Track: Message In A Bottle

Track: Can't Stand Losing You

Track: An Englishman In New York Track: Every Breath You Take

Track: Seven Days

Track: Walking On The Moon Track: Fields Of Gold

Track: Fragile

Track: Every Little Thing She Does Is Magic Track: De Do Do Do, De Da Da Da

Track: If You Love Somebody Set Them Free

Track: Brand New Day Track: Desert Rose

Track: If I Ever Lose My Faith In You

Track: When We Dance (Edit) Track: Don't Stand So Close To Me (Original Album Version)

Track: Roxanne

Track: So Lonely

Album: Fields Of Gold: The Best Of Sting 1984-1994

Track: When We Dance Track: If You Love Somebody Set Them Free

Track: Fields Of Gold

Track: All This Time Track: Fortress Around Your Heart

Track: Be Still My Beating Heart

Track: They Dance Alone Track: If I Ever Lose My Faith In You

Track: Fragile

Track: Why Should I Cry For You

Track: An Englishman In New York

Track: We'll Be Together (Previously Unreleased Version)

Track: Russians Track: This Cowboy Song

Album: Ten Summoner's Tales Track: If I Ever Lose My Faith In You

Track: Love Is Stronger Than Justice (The Munificent Seven) Track: Fields Of Gold

Track: Heavy Cloud No Rain

Track: She's Too Good For Me Track: Seven Days

Track: Saint Augustine In Hell

Track: It's Probably Me Track: Shape Of My Heart

Track: Something The Boy Said

Track: Epilogue (Nothing 'Bout Me)

Album: ...Nada Como El Sol - Selecciones Especiales En Espanol Y Portugues

Track: Mariposa Libre Track: Fragil (Portuguese)

Track: Si Estamos Juntos

Track: Ellas Danzan Solas (Cueca Solo) Track: Fragilidad

Album: Bring On The Night Track: Bring On The Night/When The World Is Running Down You Make The Best Of What's (Still Around)

Track: Consider Me Gone

Track: Low Life Track: We Work The Black Seam

Track: Driven To Tears


Track: The Dream Of The Blue Turtles/Demolition Man Track: One World (Not Three)/Love Is The Seventh Wave

Track: Moon Over Bourbon Street

Track: I Burn For You Track: Another Day

Track: Children's Crusade

Track: Down So Long Track: Tea In The Sahara

Album: ...Nothing Like The Sun Track: The Lazarus Heart

Track: Be Still My Beating Heart Track: An Englishman In New York

Track: History Will Teach Us Nothing

Track: They Dance Alone Track: Fragile

Track: We'll Be Together

Track: Straight To My Heart Track: Rock Steady

Track: Sister Moon

Track: Little Wing Track: The Secret Marriage

Album: ...All This Time Track: Fragile

Track: A Thousand Years

Track: Perfect Love...Gone Wrong Track: All This Time

Track: The Hounds Of Winter

Track: Don't Stand So Close To Me Track: When We Dance

Track: Dienda

Track: Roxanne Track: If You Love Somebody Set Them Free

Track: Brand New Day

Track: Fields Of Gold Track: Moon Over Bourbon Street

Track: If I Ever Lose My Faith In You

Track: Every Breath You Take

Album: Absolute Sting: The Unauthorised Interview

Track: Absolute Sting: The Unauthorised Interview

Album: Brand New Day

Track: A Thousand Years Track: Desert Rose

Track: Big Lie Small World

Track: After The Rain Track: Perfect Love... Gone Wrong

Track: Tomorrow We'll See

Track: Prelude To The End Of The Game Track: Fill Her Up

Track: Ghost Story

Track: Brand New Day

Album: Bring On The Night

Track: Bring On The Night/When The World Is Running Down You Make The Best Of What's (Still Around) (Live In Paris)

Track: Consider Me Gone (Live In Paris)

Track: Low Life (Live In Rome)

Track: We Work The Black Seam (Live In Paris) Track: Driven To Tears (Live In Paris)

Track: The Dream Of The Blue Turtles/Demolition Man (Live In Paris) Track: One World (Not Three)/Love Is The Seventh Wave (Live In Paris)

Track: Moon Over Bourbon Street (Live In Paris)

Track: I Burn For You (Live In Arnhem) Track: Another Day (Live In Rome)

Track: Children's Crusade (Live In Arnhem)

Track: Down So Long (Live In Arnhem)

Track: Tea In The Sahara (Live In Arnhem)


The xml returned from curl_exec ($curl) - <AlbumSearchResults xmlns="http://api.mndigital.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

- <Debug>

<Version i:nil="true" />

<QueryString i:nil="true" />

<Trace>Time: 5:27:51 PM 0.0000000 0.0000000 Timer Initialized 0.0000000 0.0000000 Volt.OpenApi.Packages.SearchPackage

GetAlbums</Trace>

</Debug>



- <Albums>

- <Album>


<Title>The Very Best Of Sting And The Police (2002 Brits Version)</Title>

- <Artist>


<Name>Sting</Name>

- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>


<Label>A&M</Label>




- <Images>

<Album75x75>http://images.musicnet.com/albums/000/673/181/s.jpeg</Album75x75>



</Images>

- <FeaturedArtists>

- <Artist>


<Name>The Police</Name>

- <Images>





</Images>

</Artist>

</FeaturedArtists>

- <Tracks>

- <Track>


<Title>Message In A Bottle</Title>

- <Artist>



- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>

<Location>rtmp://DMUS.flash-ie.musicnet.com:80/Sample</Location>


</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Can't Stand Losing You</Title>

- <Artist>



- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>







- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>An Englishman In New York</Title>

- <Artist>


<Name>Sting</Name>

- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Every Breath You Take</Title>

- <Artist>



- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Seven Days</Title>

- <Artist>


<Name>Sting</Name>

- <Images>





</Images>

</Artist>


<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Walking On The Moon</Title>

- <Artist>



- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Fields Of Gold</Title>

- <Artist>


<Name>Sting</Name>

- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Fragile</Title>

- <Artist>


<Name>Sting</Name>

- <Images>






</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Every Little Thing She Does Is Magic</Title>

- <Artist>



- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>De Do Do Do, De Da Da Da</Title>

- <Artist>



- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>If You Love Somebody Set Them Free</Title>

- <Artist>


<Name>Sting</Name>

- <Images>






</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Brand New Day</Title>

- <Artist>


<Name>Sting</Name>

- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Desert Rose</Title>

- <Artist>


<Name>Sting</Name>

- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>If I Ever Lose My Faith In You</Title>

- <Artist>


<Name>Sting</Name>

- <Images>






</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>When We Dance (Edit)</Title>

- <Artist>


<Name>Sting</Name>

- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Don't Stand So Close To Me (Original Album Version)</Title>

- <Artist>



- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>Roxanne</Title>

- <Artist>



- <Images>






</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

- <Track>


<Title>So Lonely</Title>

- <Artist>



- <Images>





</Images>

</Artist>

<Genre>Rock</Genre>






- <Mp3Rights>




</Mp3Rights>


- <SampleLocations>

- <MediaLocation>



</MediaLocation>

</SampleLocations>



</Track>

</Tracks>


- <PriceTag>





</PriceTag>


</Album>

.......................................

</Albums>

</AlbumSearchResults>


PHP Sample Code of the MNOpen API call to add a first item to a new cart

The following code uses MediaNet’s MNOpen API (Cart, namely Cart.AddItems API call) to add a first item (a track) to a new cart. It also illustrates how to use your shared secret to build a signature parameter for the API call. The code is written in PHP. At the core of this code is a call to Cart.AddItems. For additional information on Cart.AddItems API call, please see the MNOpen API documents. The PHP code (contained in index.php) wraps the Cart.AddItems API call in and does a HTTP call to the MNOpen web site to obtain an XML response of all the albums and tracks for an artist, in this case sting. A curl_exec function call is the center of the PHP code. For a full listing see PHP listing below. There are two environments that you can make your call to. An Integration Environment (IE) is used for development and testing. Clearly, you may not want to execute real transactions, such as a real credit card purchase of an album or a track, through the Production Environment, during your development and testing phase. Simply modify http://ie-api.mndigital.com to http://api.mndigital.com, in order to switch from Integration to Production environment, when final testing is completed. $theQuery parameter contains the Cart.AddItems API call and its parameters format=xml&artist=sting&rights=purchase&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=APIKey. format=xml specifies to return XML from the call. apiKey=APIKey specifies “your entity” uniquely, and thus is perhaps the most important and most common API parameter. You may want to store this in a safe file and build it into every API call Some API calls require a signature parameter added to the query string. You can do this by simply adding a call to PHP hash_hmac('md5', $theQuery, $yoursharedsecret); $theQuery = "method=Cart.AddItems";

// this is your shared secret fir IE

$secret ="yoursharedsecret";

// This is your API Key

$APIKEY="yourapikey";

$theparams= "&format=xml&APIKEY=".$APIKEY;

$theQuery = $theQuery.$theparams."&signature=".hash_hmac('md5', $theQuery.$theparams,

$secret);

The actual item to add to the new cart is specified in the XML payload of the PHP Post call. The XML to add <MnetId>12296213</MnetId> item, typically obtained from a search call to find album tracks, to the cart, is shown here: <AddItems xmlns="http://api.mndigital.com">

<Items>

<LineItem>




<Price>0.99</Price>

</LineItem>

</Items>

</AddItems>



For additional details on the Cart.AddItems API call please see section of the MNOpen API Documentation.


In order to send an XML payload using the PHP call, you need to set the following options: curl_setopt($curl, CURLOPT_POST, true);

// set the Content-Type to application/xml

curl_setopt($curl,CURLOPT_HTTPHEADER,array ("Content-Type:

application/xml"));

curl_setopt($curl, CURLOPT_POSTFIELDS, $data);

All we have to do now is post the HTTP query and parse the XML results. We then take the xml returned into a for-loop. You can of course load this into your favorite XML DOM and XPath it, or iterate over the nodes as you like, in any way you like. Ideally, check for <Success>true</Success> first. Save the cart ID (<CartId>39209</CartId>) if you like to add a second item to the same cart. Check to make sure there are no duplicate tracks in the cart using <DuplicateItemInCart>false</DuplicateItemInCart>. Check to make sure the <Count>1</Count> matches your expectation. For tracks that are sold only as part of an album, check also:



.

Full listing of the Index.php HTML page, the output, and the XML returned from the MNOpen API call, is included below for completeness.


Screen of IndexPost.php


PHP Post example of using Cart.AddItems

<html>

<head>

</head>

<body>

Adding a first item number to a new cart.

<br /><br />

<?php

// Initialize the query parameters for Cart.AddItems

// Ideally, build this query in a more general fashion,



// Please note signatures may be required for other API calls

$theQuery = "method=Cart.AddItems";

// this is your shared secret fir IE

$secret ="yoursharedsecret";

// This is your API Key

$APIKEY="yourapikey";

$theparams= "&format=xml&APIKEY=".$APIKEY;

$theQuery = $theQuery.$theparams."&signature=".hash_hmac('md5', $theQuery.$theparams,

$secret);

// Build the XML payload for post

// Ideally, build this XML payload in a more general fashion

$data = utf8_encode('

<AddItems xmlns="http://api.mndigital.com">

<Items>

<LineItem>




<Price>0.99</Price>

</LineItem>

</Items>

</AddItems>');

$url = "http://ie-api.mndigital.com?".$theQuery;//"&rpp=10";

// for debug

echo $url."<br /><br />";

// This is standard curl call of PHP


curl_setopt ($curl, CURLOPT_URL, $url);

curl_setopt($curl, CURLOPT_POST, true);

// set the Content-Type to application/xml

curl_setopt($curl,CURLOPT_HTTPHEADER,array ("Content-Type: application/xml"));

curl_setopt($curl, CURLOPT_POSTFIELDS, $data);

curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

// for debug


if (curl_errno($curl))

{

print "error";

print curl_error($curl);

}

curl_close ($curl);

//echo "<br />".$response."<br />";

// Now that we have the XML response,

// let's load it and find the cart id

$domDoc = new DOMDocument();; ;

$dom = $domDoc->loadXML($response);

// echo $response;

// this should not happen

if (!$dom) {

echo "Error while parsing the response";

exit;

}


http://ie-api.mndigital.com/?


// We have a valid XML doc loaded

$CartItemCount = $domDoc->getElementsByTagName('CartItemCount'); // All Cart Items

for ($i = 0; $i < $CartItemCount->length; $i++) {

$Nodes = $CartItemCount->item($i)->getElementsByTagName('CartId'); // Searching for

CartId

echo "CartId returned from Cart.AddItems API: ".$CartItemCount->item($i)-

>getElementsByTagName('CartId')->item(0)->nodeValue. "<br />";

}

?>

</body>

</html>

Output

Adding a first item number to a new cart. CartId returned from Cart.AddItems API: 39194 (or XXXXX)

The xml returned from curl_exec ($curl)

<CartItemCount xmlns="http://api.mndigital.com"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">



<Count>1</Count>

<Status>

<DuplicateItemInCart>false</DuplicateItemInCart>



</Status>

</CartItemCount>


JQuery Sample Code of the MNOpen API call to search for an artist’s albums and tracks

The following code uses MediaNet’s MNOpen API (Search API, namely Search.GetAlbums API call) to find all albums and tracks by an artist, in this example by “Sting”. The code is written in JQuery. At the core of this JQuery code is a $.get call to Search.GetAlbums. For additional information on Search.GetAlbums API call, please see the MNOpen API documents. The JQuery code (contained in index.htm) wraps the Search.GetAlbums API call in and does a HTTP GET call to the MNOpen web site to obtain an XML response of all the albums and tracks for an artist, in this case sting. For a full listing see JQuery listing below. There are two environments that you can make your call to. An Integration Environment (IE) is used for development and testing. Clearly, you may not want to execute real transactions, such as a real credit card purchase of an album or a track, through the Production Environment, during your development and testing phase. Simply modify http://ie-api.mndigital.com to http://api.mndigital.com, in order to switch from Integration to Production environment, when final testing is completed. $theQuery parameter contains the Search.GetAlbums API call and its parameters format=xml&artist=sting&rights=purchase&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=APIKey. format=xml specifies to return XML from the call. artist=sting specifies to return results for artist Sting. rights=purchase specifies to return results for albums and tracks which can be sold. mainArtistOnly=true specifies to return results for albums and tracks where Sting is the main artist, not a tribute band or other artist performing a sting song. page=1&pageSize=10 specify how much results to return per call to protect your buffer, but fill your display area. These parameters are used for paging. You can leave them out and get all the results in one shot. apiKey=APIKey specifies “your entity” uniquely, and thus is perhaps the most important and most common API parameter. You may want to store this in a safe file and build it into every API call All we have to do now is to perform a GET for the HTTP query and parse the XML results. We then take the xml returned into a for-each-loop, which operates on all nodes in the XML returned. You can of course load this into your favorite XML DOM and XPath it, or iterate over the nodes as you like, in any way you like. Full listing of the Index.htm HTML page and the output is included below for completeness.


Screen of Index.htm


Full HTML of Index.htm

<html>

<head>

<script type="text/javascript" src="jquery-1.3.1.js"></script>

<script type="text/javascript" >

// When the document is ready, execute mndSearch() function

$(document).ready(function() {

mndSearch();

});

function mndSearch()

{

var displayResults = ""; // Initialize display Results

// Initialize the query parameters for Search.GetAlbums API call

// Ideally, buils this query in a more general fashion,



var theQuery =

"method=Search.GetAlbums&format=xml&artist=sting&rights=purchase&includeExplicit=true&

mainArtistOnly=true&page=1&pageSize=10&apiKey=YourAPIKey";

// Display the query for show

$("#AlbumAndTrackContainer").html("http://ie-api.mndigital.com?" + theQuery);

// Execute a jQuery HTTP get using the HTTP query

// When the post is complete, execute function(xml)

// on the xml blob returned from the HTTP call

$.get("http://ie-api.mndigital.com?" + theQuery, function(xml) {

// look for Title nodes in the returned xml

$('Title', xml).each(function() {

// Get the text for each 'Title' nodes in the returned xml

// this includes Albums titles and nested track titles

var title = $(this).text();

//Make an HTML list set of the titles

displayResults = displayResults + "<li> " + title + "</li>";

});

// Show the HTML list set of the titles in the AlbumAndTrackContainer <div>

$("#AlbumAndTrackContainer").html(displayResults);

}, "xml"); // make the format XML

}

</script>

</head>

<body>

Searching for artist "sting" for all Albums and tracks titles.

<br /><br />

<div id="AlbumAndTrackContainer"></div>

<p>

</body>

</html>


IE/JavaScript Sample Code of the MNOpen API call to search for an artist’s albums and tracks

The following code uses MediaNet’s MNOpen API (Search API, namely Search.GetAlbums API call) to find all albums and tracks by an artist, in this example by “Sting”. The code is written in IE/JavaScript. At the core of this IE/JavaScript code is a .Microsoft.XMLHTTP open call to “GET” the results from Search.GetAlbums API. For additional information on Search.GetAlbums API call, please see the MNOpen API documents. The IE/JavaScript code (contained in index.htm) wraps the Search.GetAlbums API call and does a HTTP GET call to the MNOpen web site to obtain an XML response of all the albums and tracks for an artist, in this case sting. For a full listing see IE/JavaScript listing below. xmlhttp.open("GET", "http://ie-api.mndigital.com?" + theQuery, true); There are two environments that you can make your call to. An Integration Environment (IE) is used for development and testing. Clearly, you may not want to execute real transactions, such as a real credit card purchase of an album or a track, through the Production Environment, during your development and testing phase. Simply modify http://ie-api.mndigital.com to http://api.mndigital.com, in order to switch from Integration to Production environment, when final testing is completed. $theQuery parameter contains the Search.GetAlbums API call and its parameters format=xml&artist=sting&rights=purchase&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=APIKey. format=xml specifies to return XML from the call. artist=sting specifies to return results for artist Sting. rights=purchase specifies to return results for albums and tracks which can be sold. mainArtistOnly=true specifies to return results for albums and tracks where Sting is the main artist, not a tribute band or other artist performing a sting song. page=1&pageSize=10 specify how much results to return per call to protect your buffer, but fill your display area. These parameters are used for paging. You can leave them out and get all the results in one shot. apiKey=APIKey specifies “your entity” uniquely, and thus is perhaps the most important and most common API parameter. You may want to store this in a safe file and build it into every API call All we have to do now is to perform a GET for the HTTP query and parse the XML results. We then take the xml returned into a for-each-loop, which operates on all nodes in the XML returned. You can of course load this into your favorite XML DOM and XPath it, or iterate over the nodes as you like, in any way you like. When the document is ready, i.e. the XML results are returned from the API call, a MSXML2.DOMDocument XML DOM object is created and the XML results are loaded (loadXML).

xmlhttp.onreadystatechange = function() {

if (xmlhttp.readyState == 4) {

var doc = new ActiveXObject("MSXML2.DOMDocument");

doc.loadXML(xmlhttp.responseText);

var x = doc.documentElement.childNodes;


parse(x);

document.write(buffer);

}

}

A helper routine then looks for tags in the XML DOM: if (nodes[i].nodeName == "Title") Full listing of the Index.htm HTML page and the output is included below for completeness.

Screen of Index.htm


Full HTML of Index.htm

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title></title>

<script type="text/jscript">

var buffer = "";

function parse(nodes) {

var i;

for (i = 0; i < nodes.length; i++) {

if (nodes[i].hasChildNodes()) {

if (nodes[i].nodeName == "Title") {

buffer = buffer + nodes[i].text + "<br />";

}

parse(nodes[i].childNodes)

}

}

}

xmlhttp = false;

theQuery =


nly=true&page=1&pageSize=10&apiKey=YourAPIKey";

try {

xmlhttp = new ActiveXObject("Msxml2.XMLHTTP");

} catch (e) {

try {

xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");

} catch (E) {

xmlhttp = false;

}

}

xmlhttp.open("GET", "http://ie-api.mndigital.com?" + theQuery, true);

xmlhttp.onreadystatechange = function() {

if (xmlhttp.readyState == 4) {

var doc = new ActiveXObject("MSXML2.DOMDocument");

doc.loadXML(xmlhttp.responseText);

var x = doc.documentElement.childNodes;

parse(x);

document.write(buffer);

}

}

xmlhttp.send(null);

</script>

</head>

<body>

</body>

</html>


PHP/jQuery Sample Code of the MNOpen API call to search for an artist’s albums and tracks

The following code uses MediaNet Search API (Search.GetAlbums API call)to look for all albums and tracks by an artist, in this case by “Sting”. At the core of this code is a call to Search.GetAlbums. For additional information on Search.GetAlbums API call, please see the MNOpen API documents. The code is written in PHP, using a JQuery helper function.

Project files:

The PHP code (contained in getSearch.php) wraps the Search.GetAlbums API callin a code module that simply does a POST HTTP call to the MNOpen web site and obtains an XML response of all the albums and tracks for an artist, in this case sting. A curl_init function call is the center of the PHP code. For a full listing see PHP listing below.

$querystring = $_POST['querystring'];


curl_setopt ($curl, CURLOPT_URL, "http://ie-

api.mndigital.com?".$querystring."&rpp=10");

curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);


curl_close ($curl);

header('Content-Type: application/xml; charset=ISO-8859-1');

print $response;

Couple of notes worth mentioning: There are two environments that you can make your call to. An Integration Environment (IE) is used for development and testing. Clearly, you may not want to execute real transactions, such as a real credit card purchase of an album or a track, through the Production Environment, during your development and testing phase. This PHP module, among other things, allows you to simply modify one occurrence of http://ie-api.mndigital.com to http://api.mndigital.com, in order to switch from Integration to Production environment, when final testing is completed.

http://w3schools.com/php/php_post.asp

http://us3.php.net/curl_init

http://us.php.net/curl_setopt

http://us.php.net/curl_setopt

http://us.php.net/manual/en/function.curl-exec.php

http://us.php.net/manual/en/function.curl-close.php

http://us.php.net/manual/en/function.header.php


GetSearch.php helper page

Think of the code (contained in Index.php) as a JQuery helper function. The line : <script type="text/javascript" src="jquery-1.3.1.js"></script> This line enables JQuery Adds JQuery functionality to your PHP page. Function: $(document).ready(function() { // JQuery function to execute when the HTML document is ready mndSearch(); Simply specifies a function to run when the page is loaded. Think of it as a Page_load in C# .NET, or a script block that executes when the document DOM is fully loaded. Function mndSearch in the code, builds a query string that contains the Search.GetAlbums API call and the parameters format=xml&artist=sting&rights=purchase&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=APIKey. format=xml specifies to return XML from the call. artist=sting specifies to return results for artist Sting. rights=purchase specifies to return results for albums and tracks which can be sold. mainArtistOnly=true specifies to return results for albums and tracks where Sting is the main artist, not a tribute band or other artist performing a sting song. page=1&pageSize=10 specify how much to return per call to protect your buffer, but fill your display aread, these parameters are used for paging. You can leave them out and get all the results in one shot. apiKey=APIKey specifies “your entity” uniquely, and thus is perhaps the most important and most common API parameter. You may want to store this in a safe file and build it into every API call For additional information on Search.GetAlbums API parameters, please see the MNOpen API documents. For additional information on PHP, please see the PHP documentation. For additional information on JQuery, please see the JQuery documents. For a full listing see PHP/JQuery listing below.


The line $("#AlbumAndTrackContainer").html(theQuery); displays the query we built for Search.GetAlbums API parameters for debugging purposes only. All we have to do now is post the HTTP query and parse the XML results. The line $.post("getSearch.php?", {querystring:theQuery}, function(xml) posts the HTTP query. The line $.post("getSearch.php?", {querystring:theQuery}, function(xml) posts the HTTP query. We then take the xml returned and we do a for-each loop, on all nodes in the XML returned. The full returned is rather lengthy chunk, shown at the end of this document. Now you know why using JQuery as a helper. You can of course load this into your favorite XML DOM and Xpath it, or iterate over the nodes as you like, in any language you like. $('Title', xml).each(function(i) {






});

Full listing of the helper code, the full listing of the Index.php HTL page, the output, and the XML is shown below for completeness.


The full listing of Index.php is shown here:

<script type="text/javascript" src="jquery-1.3.1.js"></script> This line enables JQuery

Check for the latest version and documentation on http://docs.jquery.com/Main_Page


$(document).ready(function() { // JQuery function to execute when the HTML document is ready

mndSearch();

});


{


// Initialize the query parameters for Search.GetAlbums API call

var theQuery =


nly=true&page=1&pageSize=10&apiKey=APIKey";


$("#AlbumAndTrackContainer").html(theQuery);

// Execute a JQuery HTTP post using the HTTP query string

// When the HTTP post is completed, execute function(xml)

// on the XML blob returned from the HTTP post call

$.post("getSearch.php?", {querystring:theQuery}, function(xml) {


$('Title', xml).each(function(i) {






});




}

</script>

http://docs.jquery.com/Main_Page


Index.php using jQuery


Full HTML of Index.php

<html>

<head>

<script type="text/javascript" src="jquery-1.3.1.js"></script>


// When the document is ready, execute mndSearch() function

$(document).ready(function() {

mndSearch();

});


{


// Initialize the query parameters for search

var theQuery =


nly=true&page=1&pageSize=10&apiKey=yourApiKey";


$("#AlbumAndTrackContainer").html(theQuery);

// Execute a jQuery HTTP post using the HTTP query

// When the post is complete, execute function(xml)

// on the xml blob returned from the HTTP call

$.post("getSearch.php?", {querystring:theQuery}, function(xml) {


$('Title', xml).each(function(i) {






});




}

</script>

</head>

<body>

Searching for artist "sting" for all Albums and all tracks.

<br /><br />

<div id="AlbumAndTrackContainer"></div>

<p>

</body>

</html>


PERL Sample Code of the MNOpen API call to search for an artist’s albums and tracks

The following code uses MediaNet’s MNOpen API (Search, namely Search.GetAlbums API call) to look for all albums and tracks by an artist, in this example, for all albums and tracks by “Sting”. The code is written in PERL. At the core of this code is a call to Search.GetAlbums. For additional information on Search.GetAlbums API call, please see the MNOpen API documents. The PERL code (contained in index.Perl) wraps the Search.GetAlbums API call in an HTTP GET call to the MNOpen web site to obtain an XML response. The XML response contains all the albums and tracks for an artist, in this case sting. An LWP::UserAgent object is the center of the PERL code. For a full listing see PERL listing below. There are two environments that you can make your call to.

An Integration Environment (IE) is used for development and testing.

Clearly, you may not want to execute real transactions, such as a real credit card

purchase of an album or a track, through the Production Environment, during your

development and testing phase.

Simply modify http://ie-api.mndigital.com to http://api.mndigital.com, in order to switch

from Integration to Production environment, when final testing is completed.

$theQuery parameter contains the Search.GetAlbums API call and its parameters format=xml&artist=sting&rights=purchase&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=APIKey.

format=xml specifies to return XML from the call.

artist=sting specifies to return results for artist Sting.

rights=purchase specifies to return results for albums and tracks which can be sold.

mainArtistOnly=true specifies to return results for albums and tracks where Sting is the

main artist, not a tribute band or other artist performing a sting song.

page=1&pageSize=10 specify how much results to return per call to protect your buffer,

but fill your display area. These parameters are used for paging. You can leave them out

and get all the results in one shot.

apiKey=APIKey specifies “your entity” uniquely, and thus is perhaps the most important

and most common API parameter. You may want to store this in a safe file and build it

into every API call

Some API calls require a signature parameter added to the query string. You can do this

by simply adding a call to PERL hash_hmac('md5', $theQuery, $yoursharedsecret);

my $httpRequest =

HTTP::Request->new($uRLMethod,$server.$method.$postFormat.$params.$apiKey);

Where:

my $uRLMethod = 'GET';

my $server = "http://ie-api.mndigital.com?";


my $method = 'method=Search.GetAlbums';

my $postFormat = '&format=xml';

my $params =

'&title=&artist=sting&artistMnetId=&rights=purchase&keyword=&includeExplicit=

true&mainArtistOnly=true&page=1&pageSize=10';

my $apiKey = '&apiKey=yourAPIKey;

The actual URL used in the GET method of HTTP::Request is: http://ie-api.mndigital.com?method=Search.GetAlbums&format=xml&title=&artist=sting&artistMnetId=&rights=purchase&keyword=&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=yourapikey All we have to do now is post the HTTP query and parse the XML results. An XML::DOM::Parser object is used for this part.

my $responseDoc = $parser->parse($httpResponse->content);

We then take the xml returned into a for-each-loop, which operates on all nodes in the XML returned. You can of course load this into your favorite XML DOM and XPath it, or iterate over the nodes as you like, in any way you like. #go through each XML Album node

for(my $i = 0; $i < $albumNodes->getLength(); $i++)

{

#Get this Album node

my $thisNode = $albumNodes->item($i);

print "<BR />Album: " . $thisNode->getElementsByTagName('Title')->item(0)-

>getChildAtIndex(0)->getNodeValue() . "<br />";

#Get the tracks and print track titles

my $Titles = $thisNode->getElementsByTagName('Title', 1);

for ($j = 1; $j < $Titles->getLength(); $j++) {

print " Track: " . $Titles->item($j)-

>getChildAtIndex(0)->getNodeValue() . "<br />";

}

}

Full listing of the Index.Perl HTML page, the output, and the XML returned from the MNOpen API call, is included below for completeness.

http://ie-api.mndigital.com/?method=Search.GetAlbums&format=xml&title=&artist=sting&artistMnetId=&rights=purchase&keyword=&includeExplicit=true&mainArtistOnly=true&page=1&pageSize=10&apiKey=yourapikey





Screen of Index.Perl


Full HTML of Index.Perl

use LWP::UserAgent;

use HTTP::Request;

use HTTP::Response;

use XML::DOM;

use CGI qw(:standard);

use CGI::Carp qw(fatalsToBrowser);

#############################################################################

#UserAgent - used to process the web requests.

my $objUserAgent = LWP::UserAgent->new;

#Tell IIS what type of content we are returning, See

http://support.microsoft.com/kb/145661

print "Content-Type: text/html\n\n\n";

#Get the HTTP::Headers object needed for calls to the MNDigital API

my $httpHeader = geteMNDHeaders();

#Get the body of the XML request for this call

my $requestXmlBody = buildAPIXmlBody();

# Ideally build this in a more generic manner to cover all APIs

#Create a HTTP:Request to the IE server, using the headers and body specified

my $uRLMethod = 'GET';

my $server = "http://ie-api.mndigital.com?";

my $method = 'method=Search.GetAlbums';

my $postFormat = '&format=xml';

my $params =

'&title=&artist=sting&artistMnetId=&rights=purchase&keyword=&includeExplicit=

true&mainArtistOnly=true&page=1&pageSize=10';

my $apiKey = '&apiKey= yourapikey'; # print $method, $server.$method.$postFormat.$params.$apiKey;

#############################################################################

# Make the API call

my $httpRequest = HTTP::Request->new($uRLMethod,

$server.$method.$postFormat.$params.$apiKey);

#Send the request and get HTTP::Response object

my $httpResponse = $objUserAgent->request($httpRequest);

#See if there were any errors getting the response

if ($httpResponse->is_error)

{

#There were errors

print $httpResponse->error_as_HTML;

}

else # No Errors

{

#Create a new DOM::Parser

my $parser = new XML::DOM::Parser();


my $responseDoc = $parser->parse($httpResponse->content);

#Look for Title nodes in the XML

my $albumNodes = $responseDoc->getElementsByTagName('Album', 1);

print "<B>For Artist Sting, Medianet Search API returned the following

albums and title(s):</B>,<BR />";

if($albumNodes->getLength() > 0)

{

#go through each XML Album node

for(my $i = 0; $i < $albumNodes->getLength(); $i++)

{

#Get this Album node

my $thisNode = $albumNodes->item($i);

print "<BR />Album: " . $thisNode-

>getElementsByTagName('Title')->item(0)->getChildAtIndex(0)->getNodeValue() .

"<br />";

#Get the tracks and print track titles

my $Titles = $thisNode->getElementsByTagName('Title', 1);

for ($j = 1; $j < $Titles->getLength(); $j++) {

print " Track: " . $Titles-

>item($j)->getChildAtIndex(0)->getNodeValue() . "<br />";

}

} #for(my $i = 0; $i < $albumNodes->getLength(); $i++)

} #if($albumNodes->getLength() > 0)

$responseDoc->dispose();

} #else # No Errors

exit;

#############################################################################

# Builds the XML request body to send to the server

# containing the data needed by the API

sub buildAPIXmlBody()

{

#build a string represntation of the XML, containg all the post data

my $xmlBody = ""; # there is no post data for this API

#return the XML string

return $xmlBody;

}

#############################################################################

# Constuct and return HTTP::Headers for the API call

sub geteMNDHeaders()

{

#Create new HTTP::Headers object

my $httpHeader = HTTP::Headers->new;

#set all the headers with their values

$httpHeader->push_header('Content-Type: text/html\n\n\n"');

#return the object

return $httpHeader;

}


Output from Index.Perl

For Artist Sting, Medianet Search API returned the following albums and title(s):, Album: If On A Winter's Night Track: Gabriel's Message Track: Soul Cake Track: There Is No Rose Of Such Virtue Track: The Snow It Melts The Soonest Track: Christmas At Sea Track: Lo How A Rose E'er Blooming Track: Cold Song Track: The Burning Babe Track: Now Winter Comes Slowly Track: The Hounds Of Winter Track: Balulalow Track: Cherry Tree Carol Track: Lullaby For An Anxious Child Track: Hurdy Gurdy Man Track: You Only Cross My Mind In Winter Album: The Very Best Of Sting And The Police (2002 Brits Version) Track: Message In A Bottle Track: Can't Stand Losing You Track: An Englishman In New York Track: Every Breath You Take Track: Seven Days Track: Walking On The Moon Track: Fields Of Gold Track: Fragile Track: Every Little Thing She Does Is Magic Track: De Do Do Do, De Da Da Da Track: If You Love Somebody Set Them Free Track: Brand New Day Track: Desert Rose Track: If I Ever Lose My Faith In You Track: When We Dance (Edit) Track: Don't Stand So Close To Me (Original Album Version) Track: Roxanne Track: So Lonely Album: Fields Of Gold: The Best Of Sting 1984-1994 Track: When We Dance Track: If You Love Somebody Set Them Free Track: Fields Of Gold Track: All This Time Track: Fortress Around Your Heart Track: Be Still My Beating Heart Track: They Dance Alone Track: If I Ever Lose My Faith In You Track: Fragile Track: Why Should I Cry For You Track: An Englishman In New York Track: We'll Be Together (Previously Unreleased Version) Track: Russians Track: This Cowboy Song Album: Bring On The Night Track: Bring On The Night/When The World Is Running Down You Make The Best Of What's (Still Around) (Live In Paris) Track: Consider Me Gone (Live In Paris) Track: Low Life (Live In Rome) Track: We Work The Black Seam (Live In Paris) Track: Driven To Tears (Live In Paris) Track: The Dream Of The Blue Turtles/Demolition Man (Live In Paris) Track: One World (Not Three)/Love Is The Seventh Wave (Live In Paris) Track: Moon Over Bourbon Street (Live In Paris)


Track: I Burn For You (Live In Arnhem) Track: Another Day (Live In Rome) Track: Children's Crusade (Live In Arnhem) Track: Down So Long (Live In Arnhem) Track: Tea In The Sahara (Live In Arnhem) Album: Still Be Love In The World Track: After The Rain Has Fallen (Live) Track: A Thousand Years (Nitin Sawhney Mix) Track: Perfect Love Gone Wrong (Live) Track: Every Breath You Take (Live) Track: Fragile (Live) Track: Brand New Day (Cornelius Mix) Track: Desert Rose (Melodic Club Mix Radio Edit) Album: ...All This Time Track: Fragile Track: A Thousand Years Track: Perfect Love...Gone Wrong Track: All This Time Track: The Hounds Of Winter Track: Don't Stand So Close To Me Track: When We Dance Track: Dienda Track: Roxanne Track: If You Love Somebody Set Them Free Track: Brand New Day Track: Fields Of Gold Track: Moon Over Bourbon Street Track: If I Ever Lose My Faith In You Track: Every Breath You Take Album: ...Nada Como El Sol - Selecciones Especiales En Espanol Y Portugues Track: Mariposa Libre Track: Fragil (Portuguese) Track: Si Estamos Juntos Track: Ellas Danzan Solas (Cueca Solo) Track: Fragilidad Album: ...Nothing Like The Sun Track: The Lazarus Heart Track: Be Still My Beating Heart Track: An Englishman In New York Track: History Will Teach Us Nothing Track: They Dance Alone Track: Fragile Track: We'll Be Together Track: Straight To My Heart Track: Rock Steady Track: Sister Moon Track: Little Wing Track: The Secret Marriage Album: Absolute Sting: The Unauthorised Interview Track: Absolute Sting: The Unauthorised Interview Album: Brand New Day Track: A Thousand Years Track: Desert Rose Track: Big Lie Small World Track: After The Rain Track: Perfect Love... Gone Wrong Track: Tomorrow We'll See Track: Prelude To The End Of The Game Track: Fill Her Up Track: Ghost Story Track: Brand New Day


I/we make no warranties whatsoever as to the fitness of this or any sample code provided or as to its suitability for any purpose(s), including the purpose for which I/we may claim that it functions. /we are including this sample code in the hope that it will be useful to you in jumpstarting your development, and in the belief that it is free from serious errors. However, I/we make no guarantees in either of these regards. In addition to the above disclaimers, this code sample is distributed under the terms of the MediaNet customer agreements.


Appendix D: Change History / Errata

June 2009

Added details on generating call signatures

Corrections to Search Package

Updates to Appendix A: MN Open Customer (Partner) Fact Sheet

Updates to Required Retail Price and Affected Label Owners

Updated the Samples on pages 6-8

Added information about album and artist image sizes

Updated the Package and Method Overview

Updated the Data Types

Added discussion about using the POST body for those methods that require it

Added definitions for Partner.UseBalance and Partner.RefillBalance

Updated definition for Cart.GetCartByUser -- it has changed; please update any code that utilized the old version.

Minor corrections throughout

July 2009

Moved the Errata to Appendix D

Updated Search Package o Removed "keyword" from Search.ContentMatch

Addition of Track.GetLocations to Track Package

Added information about XML POST bodies requiring Pascal Case; related edits throughout

Expanded the Pricing, Required Retail Pricing and Tax Handling section to (a) apply also to WMG content, and (b) with more detail about requirements related to the Sony Agency Model

Updates and corrections to the Signature Generation section

Updates and corrections to the Cart Package

Updates and corrections to the Purchase Package

Updates and corrections to the User Package o User.Login is deprecated and no longer required

Additions to Common Response Data Elements

Addition of following sections: o Sample Streaming with Flash: RESOURCE and LOCATION o PHP, cUrl, and Content-type Header Setting o Download Locations and Single Download o The MediaNet Environments: Integration (IE) and Production (PROD) o How to search for International Language Data

Updated Common Errors section

Updates to Report.GetOrderHistory (all SortTypes included)

Updates and corrections to the Use Cases

September 2009

Updated Search.GetAlbums for providing locations

Added Static Sample URLs Feature

Added "UserDomain is required" to Cart.Purchase

Added Bitrate info: 320 vs. 256 kbps

Removed Tax requirement for Colorado

Promoted Image Data heading

Expand Purchase.UseBalance description to mandate that balances must always be positive

Expanded the section on page 5 about Account Balance model


Added Album-only handling

Added Best Practice for parsing XML responses

Updated Purchase.UseCreditCard, to specify both CreditCard and BillingAddress rather than user info

Added "main artist only” flag to search API

Added GetAMGData API

Changed the word "partner" to "customer" without changing the naming of the APIs, parameters or Partner package.

October 2009

Report.getOrderHistory Minor typo fix in example, parameter userID changed to Username.

Added link to "test player" for use to test the media locations returned from the API. Added Label.GetLabelOwners API call to get a current list of Label owners.

Added MN Open API Metadata

Added Album / Track revocation

Expanded on use cases

Added Friendly File Names

Added Sony Download terms

Added <PopularityRanking>

Updated GetOrderHistory 'pageNumber' and 'recordsToReturn' parameters

Added Sample Code

November 2009

Added four more sample code examples in Appendix C

Expanded the "Generating Signatures with your Shared Secret" section

Added PHP POST and PHP Signature generation code examples

Added Best Practices section

Added new Label.GetLabelOwners API call definition and example

Added username parameter to User.Update API call as well as typical request response information

mn open: api implementation guide

Documents