MN Open: API Implementation Guide September 2009
Table of Contents MN Open: API Implementation Guide ...... 1 Customer Support with the MN Open API ...... 2 Introduction ...... 3 Security: Customer Authentication and Encryption ...... 4 Transaction Options ...... 4 Credit Card Payments ...... 4 Account Balance Payments ...... 4 Pricing, Required Retail Price and Tax Handling ...... 5 Territory Restriction ...... 6 Bitrate information ...... 6 The MN Open APIs ...... 7 MN Open API Package and Method Overview ...... 10 Global Parameters ...... 12 Paging ...... 12 Generating Signatures with your Shared Secret ...... 12 Tips for Methods That Require a POST Body ...... 13 Sample Streaming with Flash: RESOURCE and LOCATION ...... 13 PHP, cUrl, and Content-type Header Setting ...... 14 Download Locations and Single Download ...... 14 Environments: Integration (IE) and Production (PROD) ...... 14 How to Search for International Language Data ...... 15 Handling Album-only Tracks ...... 16 Image Data ...... 16 Common Response Data Elements ...... 17 Common Errors ...... 21 Content Discovery ...... 22 Search.GetTracks ...... 22 Search.GetAlbums ...... 23 Search.GetArtists ...... 24 Search.GetGeoLocation ...... 24 Search.ContentMatch...... 25 Track.Get ...... 26 Track.GetLocations ...... 26 Album.GetTracks ...... 27 Artist.GetAlbums ...... 28 Artist.GetTracks ...... 28 Provisioning ...... 30 User.Create ...... 30 User.Get ...... 31 User.IsUsernameAvailable ...... 32 User.Login - DEPRECATED ...... 32 User.SetPassword ...... 33 User.Update ...... 34 Cart.AddItems ...... 35 Cart.Clear ...... 37 Cart.Get ...... 37 Cart.GetCartByUser ...... 38 Cart.GetDownloadLocations ...... 38 Cart.Purchase ...... 39
MediaNet Digital Confidential Page 1 of 69
Cart.RemoveItems ...... 41 Purchase.UseBalance ...... 42 Purchase.UseCreditCard ...... 45 Management ...... 49 Partner.GetAMGData ...... 49 Partner.GetBalance ...... 50 Partner.RefillBalance ...... 50 Report.GetOrderHistory ...... 52 Use Cases ...... 54 CART MANAGEMENT USE CASES ...... 54 USER MANAGEMENT USE CASES ...... 55 Appendix A: Sony Agency Model Nexuses and Tax Rates ...... 57 Appendix B: Label Owners by Identifier and Name ...... 58 Appendix C: Change History / Errata ...... 68
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 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.
MediaNet Digital Confidential Page 2 of 69
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 seven 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.
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 our enterprise-class media platform and returns responses as XML or JSON. The API gives you access to as rich of a functionality set as our enterprise class SOAP-based Web Services -- without the additional complexity and overhead of the SOAP envelope, versioning, and session-based interactions. Our MN Open API is stateless, easy to work with using any programming language, and is highly functional (including full transactional capabilities).
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 JSON2.
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 format3) 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 • 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.
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.
MediaNet Digital Confidential Page 3 of 69
To be clear: since the service is HTTP-based, all responses will have an HTTP protocol response code and status message5 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 hash6 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://.
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 determined by our platform and 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.
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 (there is a 3% processing fee), via API (Partner.RefillBalance), or check. To fund or refill by check, please contact us directly via [email protected].
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
MediaNet Digital Confidential Page 4 of 69
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 must add to any checkout page, receipt pages, and receipt emails that contain Sony content the following "blurb" exactly as written -- no changes are acceptable:
"Any permanent downloads of Sony Music Entertainment content are sold directly by SBME 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 B: Sony Agency Model Nexuses and Tax Rates. 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.
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.
MediaNet Digital Confidential Page 5 of 69
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.
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 a Album.GetTracks API call using mnetId= 26685813. Please note the
-
MediaNet Digital Confidential Page 6 of 69
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=APIKEY&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,
MediaNet Digital Confidential Page 7 of 69
"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
MediaNet Digital Confidential Page 8 of 69
MediaNet Digital Confidential Page 9 of 69
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 SSL Required? Required? Content Discovery Search Package Contains methods for searching the MediaNet catalog. GetTracks Searches for tracks by title, artist, album, No No 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 GetAlbums Searches for albums by title, artist, and/or No No 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. GetArtists Searches for artists by name and/or keyword. No No Returns artist matches and artist images if any GetGeoLocation Does a lookup by IP. No No Returns two-letter country code (ISO 31668) ContentMatch Returns the single best track matched in real- No No 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. Track Package Contains methods for retrieving information about a track. Get Retrieves by MediaNetID (mnetid) the No No metadata about a specific track, including artist and album info, etc. GetLocations Retrieves media locations for 30-second Yes No samples. Album Package Contains methods for retrieving information about an album. GetTracks Retrieves by MediaNetID (mnetid) the No No metadata about a specific album, including artist and album info, with tracks, etc. Artist Package Contains methods for retrieving information about an artist. GetAlbums Retrieves by MediaNetID (mnetid) the No No 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.
8 http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
MediaNet Digital Confidential Page 10 of 69
Package/Method Description Signature SSL Required? Required? GetTracks Retrieves by MediaNetID (mnetid) the No No 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. Provisioning User Package Contains methods for creating, updating, and authenticating user accounts. Create Creates a user associated with your PartnerID Yes Yes Returns the user's details Get Retrieves information about a specific user No No Returns the user's details IsUsernameAvailable Checks whether a username is available No No Usernames are unique by customer. Login DEPRECATED Logs in a user by username and password Yes Yes Returns an Auth Token SetPassword Sets (changes) a user's password. Yes Yes Update Updates (changes) information about a Yes Yes specific user. Cart Package Contains methods for creating, updating, and purchasing items. AddItems Adds an item to cart. If no CartId is Yes No referenced, a new one is created. Returns an existing or new CartId, plus a count of items in the cart. Clear Clears (empties) an existing CartId Yes No Get Retrieves the details of a specific cart. Yes No Returns sub-total, tax, total, and line items including track and album info, and artist and album art GetCartByUser Retrieves a CartId, if any, associated to a Yes No user, including the line item(s) in it, along with sub-total, tax, and grand total. GetDownloadLocations Retrieves the media download locations Yes No (URLs) for objects in an OrderID (see Cart.Purchase below) Purchase Purchases a cart, using a credit card. Yes Yes Returns (on success) an OrderID to reference by GetDownloadLocations (see above). For purchases without a cart, see the Purchase package below. RemoveItems Removes one or more item(s) from an existing Yes No cart. Purchase Package Contains methods for purchasing outside a shopping cart paradigm. UseBalance Purchases a single or multiple tracks and/or Yes Yes albums in a single transaction, debiting your Account Balance. For purchases utilizing our shopping cart functionality, see Cart.Purchase above. UseCreditCard Purchases a single or multiple tracks and/or Yes Yes albums, using a credit card. For purchases utilizing our shopping cart functionality, see Cart.Purchase above.
MediaNet Digital Confidential Page 11 of 69
Package/Method Description Signature SSL Required? Required? Management Partner Package Contains methods for managing your account balance GetAMGData Retrieves AMG biography for an artist and/or Yes No AMG review for an album GetBalance Retrieves your current account balance Yes No RefillBalance Refills (or adds to) your account balance. Yes No Please note that we charge a 3% convenience fee for credit card refills. Report Package Contains methods for generating reports. GetOrderHistory Retrieves orders by end user username within Yes No a range of "start" and "end" dates
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=PartnerApiKey&format=xml&u serIP=enduserIPAddress&siteDomain=domainname&signature=c8443d830782243cc23d0448c7 774fea
MediaNet Digital Confidential Page 12 of 69
If you have code already for performing the HMAC-MD5 transformation, then it might look like this:
Signature=Base64(HMACMD5("method=purchase.usecreditcard&apiKey=PartnerApiKey&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 the future we will provide sample code for HMAC-MD5. See also Footnote #6 on page 4.
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 "element X is missing" even though you are passing it in, double-check both the case and order of the elements against the examples.
Sample Streaming 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):
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
9 http://en.wikipedia.org/wiki/Pascal_case
MediaNet Digital Confidential Page 13 of 69
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: • Download locations 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.
Samples are typically of short (~30 second) length. Download locations for samples:
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) Not live; test card numbers The same one dummy download locations is returned http://ie-api.mndigital.com are acceptable, e.g., for all purchases: Visa: http://DMUS.download-ie.musicnet.com/sample/download/location/ 4111111111111111 MasterCard: 5500000000000004
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 track locations will remain valid for one year. Sample locations do not expire.
MediaNet Digital Confidential Page 14 of 69
AmEx: 340000000000009 Discover: 6011000000000004 Production (PROD) Live cards Real content is provided by real download locations. http://api.mndigital.com For low-cost testing in PROD, a special MediaNet- owned album with four tracks has been created. The album is $0.20 and the tracks are $0.10 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 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):
MediaNet Digital Confidential Page 15 of 69
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://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:
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"
MediaNet Digital Confidential Page 16 of 69
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 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
MediaNet Digital Confidential Page 17 of 69
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
MediaNet Digital Confidential Page 18 of 69
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
MediaNet Digital Confidential Page 19 of 69
• 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
MediaNet Digital Confidential Page 20 of 69
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 This means something fundamentally wrong with the unknown error occurred request: malformed, missing parameters, incorrect format (content type), etc. Please double-check and try again. 105 Application Error: The MN Open API sits on top of the MediaNet Digital Exception from the Enterprise Platform: Web Services and Catalog. Platform Layer 110 Application Error: Error from Data Access Layer 115 Application Error: Service There was a timeout somewhere in the stack. temporarily unavailable 120 Application Error: Method has not been implemented 200 Input Error: Invalid parameter 205 Invalid API key 210 Incorrect signature 300 Permissions error
MediaNet Digital Confidential Page 21 of 69
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 No XML String in, JSON or XML. (Values: XML, JSON) IncludeExplicit Whether to include items with No True Boolean explicit content (title, lyrics). Keyword Search term to be used in a No String combined Album, Artist, and Track search that will return tracks Page The page number that should be No 1 Integer retrieved PageSize The number of items per page. No 5 Integer Rights The content right to filter by. No purchase String Possible values are: "purchase" (Values: and "sample." The default is purchase, "purchase," and is what is used if sample) other material is passed in. Title The track's title. No String
Example: ?method=search.gettracks&artist=Pearl+Jam&page=1&pageSize=10&ApiKey=PartnerApiKey&ri ghts=purchase
MediaNet Digital Confidential Page 22 of 69
Returns: TrackSearchResults • Int TotalTracks • Track [] Tracks; see Common Response Data Elements above
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. Artist The name of an artist. No String Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) IncludeExplicit Whether to include items with No True Boolean explicit content (title, lyrics). Keyword Search term to be used in a No String combined Album, Artist, and Track search that will return albums mainArtistOnly ensures that results of a No false Boolean command contain only those where the specified artist is the primary or main artist Page The page number that should be No 1 Integer retrieved PageSize The number of items per page. No 5 Integer Rights The content right to filter by. No purchase String (Values: Possible values are: "purchase" purchase, and "sample." The default is sample) "purchase," and is what is used if other material is passed in. Title The album's title. No String
Example: ?method=search.getalbums&artist=Pearl+Jam&mainArtistOnly=true&page=1&pageSize=10&Api Key=PartnerApiKey&rights=purchase
Returns: AlbumSearchResults • Int TotalResults • Album [] Albums; see Common Response Data Elements above
MediaNet Digital Confidential Page 23 of 69
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) Keyword Search term to be used in a No String combined Album, Artist, and Track search that will return albums Name The name of an artist. No String Page The page number that should be No 1 Integer retrieved PageSize The number of items per page. No 5 Integer
Example: ?method=search.getartists&name=Pearl+Jam&page=1&pageSize=10&ApiKey=PartnerApiKey
Returns: ArtistSearchResults • Int TotalResults • Artist [] Artists; see Common Response Data Elements above
Search.GetGeoLocation
Description: Does a lookup by IP Returns: Returns two-letter country code (ISO 316611) 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 Yes String invoke. Addr The IP address to look up Yes String Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON)
Example: ?method=search.getgeolocation&addr=67.88.218.200&ApiKey=PartnerApiKey
Returns: Location (two-letter country code)
11 http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
MediaNet Digital Confidential Page 24 of 69
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. Album The album's title. No String AMGID The AMG (All Music Guide) No String identifier for an asset Very Important: the AMGID must be passed in using as many "%20" for spaces as exist in the AMGID itself. Artist The name of an artist. No String Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) IncludeExplicit Whether to include items with No True Boolean explicit content (title, lyrics). ISRC International Standard No String 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. Rights The content right to filter by. No Purchase String (Values: Possible values are: "purchase" purchase, and "sample." The default is sample) "purchase," and is what is used if other material is passed in. Title The track's title. Use title with at No String least one of artist or album. UPC may be used in place of album title. UPC Universal Product Code. No String Applies to albums, not tracks.
Example: ?method=search.contentmatch&isrc={ISRC}&apiKey=PartnerApiKey&rights=purchase
MediaNet Digital Confidential Page 25 of 69
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 Method The name of the method to invoke. Yes String Format The format the response should be in, No XML String (Values: JSON or XML. XML, JSON) MnetId The MNetId for a track. Mnetid is Yes String returned in the various methods of the search package.
Example: ?method=track.get&mnetId= 12296213&ApiKey=PartnerApiKey
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: Name Description Required? Default Value Type 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, No XML String JSON or XML. (Values: XML, JSON)
MediaNet Digital Confidential Page 26 of 69
mnetIds The MNetId for one or more Tracks. Yes String Delimited by '|' or ',' Note: if you use '|' you must URL- encode them before the hash. Rights The content right to filter by. Possible No purchase String values are: "purchase" and "sample." (Values: The default is "purchase," and is what is purchase, used if other material is passed in. sample) Signature All other query string parameters in an Yes String HMAC-MD5 hash. The Partner's Shared Secret is the key.
Example: ?method=track.getLocations&mnetIds=13374|13375&rights=sample&apiKey=PartnerApiKey &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: Name Description Required? Default Value Type 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, No XML String (Values: JSON or XML. XML, JSON) MnetId The MNetId for an album. Mnetid is Yes String returned in the various methods of the search package.
Example: ?method=album.getTracks&mnetId=9565107&ApiKey=PartnerApiKey
Returns: AlbumMetadata; see Common Response Data Elements above
MediaNet Digital Confidential Page 27 of 69
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: Name Description Required? Default Value Type ApiKey Partner's API key. No String Method The name of the method to invoke. Yes String Format The format the response should No XML String be in, JSON or XML. (Values: XML, JSON) IncludeExplicit Whether to include items with No True Boolean explicit content (title, lyrics). Shorten to explicit. MnetId The MNetId for an Artist. Mnetid is Yes String returned in the various methods of the search package. Page The page number that should be No 1 Integer retrieved Pagesize The number of items per page. No 5 Integer Rights The content right to filter by. No Purchase String Possible values are: "purchase" (Values: and "sample." The default is purchase, "purchase," and is what is used if sample) other material is passed in.
Example: ?method=artist.getAlbums&mnetId=43089&page=1&pageSize=10&rights=purchase&includeExpli cit=true&ApiKey=PartnerApiKey
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.
MediaNet Digital Confidential Page 28 of 69
Parameters: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to invoke. Yes String Format The format the response should No XML String be in, JSON or XML. (Values: XML, JSON) IncludeExplicit Whether to include items with No True Boolean explicit content (title, lyrics). Shorten to explicit. MnetId The MNetId for an Artist. Mnetid is Yes String returned in the various methods of the search package. Page The page number that should be 1 Integer retrieved PageSize The number of items per page. 5 Integer Rights The content right to filter by. No Purchase String Possible values are: "purchase" (Values: and "sample." The default is purchase, "purchase," and is what is used if sample) other material is passed in.
Example: ?method=artist.getTracks&mnetId=43089&page=1&pageSize=10&rights=purchase&includeExpli cit=true&ApiKey=PartnerApiKey
Returns: ArtistMetadata; see Common Response Data Elements above
MediaNet Digital Confidential Page 29 of 69
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: Name Description Required? Default Value Type In the Query String... 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, No XML String JSON or XML. (Values: XML, JSON) Signature All other query string parameters in an Yes String HMAC-MD5 hash. The Partner's Shared Secret is the key. 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 Yes String the USER MANAGEMENT USE CASES "Create a User" for important information. Password The user's desired password Yes String EmailAddress The user's desired email address; please Yes String see the USER MANAGEMENT USE CASES "Create a User" for important information. AllowNewsletter The user's preference about whether to Yes False Boolean receive the MN Open newsletter. AllowHtmlEmail The user's preference about whether to Yes True Boolean receive email formatted in HTML or plaintext.
MediaNet Digital Confidential Page 30 of 69
Example in JSON: ?method=user.create&ApiKey=PartnerApiKey&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=PartnerApiKey&format=XML&signature=Signature
Body of POST:
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) Username Username of the specific user Yes String
MediaNet Digital Confidential Page 31 of 69
Example: ?method=user.get&apiKey=PartnerApiKey&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: Name Description Required? Default Value Type 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 No XML String or XML. (Values: XML, JSON) Username Username to check availability of. Yes String
Example: ?method=user.isUsernameAvailable&username=alfred1234&ApiKey=PartnerApiKey&format=JS ON
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: Name Description Required? Default Value Type In the Query String... 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, No XML String JSON or XML. (Values: XML, JSON) Signature All other query string parameters in an Yes String HMAC-MD5 hash. The Partner's Shared Secret is the key. In the POST Body... Password The user's password. Yes String
MediaNet Digital Confidential Page 32 of 69
Name Description Required? Default Value Type Username The user's username. Yes String
Example in JSON: ?method=user.login&ApiKey=PartnerApiKey&format=JSON&signature=Signature
Body of POST: { "Username": "Username", "Password": "password" }
Example in XML: ?method=user.login&ApiKey=PartnerApiKey&format=XML&signature=Signature
Body of POST:
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. Format The format the response No XML String should be in, JSON or XML. (Values: XML, JSON) New Password The new password for the Yes String user. Old Password The original password for the Yes String user. Signature All other query string Yes String parameters in an HMAC-MD5 hash. The Partner's Shared Secret is the key. Username The username for the Yes String username whose password is being changed.
MediaNet Digital Confidential Page 33 of 69
Example: ?method=User.SetPassword&format=xml&username=alfred123&oldPassword=password1234&n ewPassword=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: Name Description Required? Default Value Type In the Query String... 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, No XML String JSON or XML. (Values: XML, JSON) Signature All other query string parameters in an Yes String HMAC-MD5 hash. The Partner's Shared Secret is the key. 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 Yes String the USER MANAGEMENT USE CASES "Create a User" for important information. Password The user's desired password Yes String EmailAddress The user's desired email address; please Yes String see the USER MANAGEMENT USE CASES "Create a User" for important information. AllowNewsletter The user's preference about whether to Yes False Boolean receive the MN Open newsletter. AllowHtmlEmail The user's preference about whether to Yes True Boolean receive email formatted in HTML or plaintext.
Example in JSON: ?method=user.update&ApiKey=PartnerApiKey&format=JSON&signature=Signature
Body of POST: { "User": { "FirstName": "First", "LastName": "Last", "Username": "username", "Password": "password", "EmailAddress": "[email protected]",
MediaNet Digital Confidential Page 34 of 69
"AllowNewsletter": "true", "AllowHtmlEmail": "true", } }
Example in XML: ?method=user.update&ApiKey=PartnerApiKey&format=XML&signature=Signature
Body of POST:
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: Name Description Required? Default Value Type In the Query String... ApiKey Partner's API key. Yes String Method The name of the method to invoke. Yes String CartId The Id for the cart that the items will be No Integer added to. If empty, a new cart is created. Format The format the response should be in, No XML String JSON or XML. (Values: XML, JSON)
MediaNet Digital Confidential Page 35 of 69
Signature All other query string parameters in an Yes String HMAC-MD5 hash. The Partner's Shared Secret is the key. In the POST Body... MnetId The MediaNet item identifier for track or Yes String album. ItemType The type of item being purchased. Yes String (Values: Track, Album) Format The codec of the item purchased; MP3 is Yes String the only current value supported 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=PartnerApiKey&format=JSON&signature=Sign ature
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=PartnerApiKey&format=XML&signature=Signat ure
Body of POST:
MediaNet Digital Confidential Page 36 of 69
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. CartId The Id for the cart to clear. Yes Integer Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON)
Example: ?method=cart.clear&CartId=123456&ApiKey=PartnerApiKey&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 Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to invoke. Yes String CartId The Id for the cart to retrieve. Yes Integer Format The format the response should be in, No XML String JSON or XML. (Values: XML, JSON) Signature All other query string parameters in an Yes String HMAC-MD5 hash. The Partner's Shared Secret is the key.
Example: ?method=cart.get&CartId=123456&ApiKey=PartnerApiKey&format=JSON&signature=Signature
Returns: ShoppingCart; see Common Response Data Elements above
MediaNet Digital Confidential Page 37 of 69
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) State The end-user's state (physical No String location). Used to calculate tax for cart items. (If state is passed in, tax will be calculated; else not.) Username The Username of the user in Yes String question.
Example: ?method=cart.getCartByUser&username=username&ApiKey=PartnerApiKey&format=JSON&sig nature=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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. OrderID The identifier for the order. Yes Int Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) Signature All other query string parameters Yes String in an HMAC-MD5 hash. The Partner's Shared Secret is the key.
Example: ?method=cart.getDownloadLocations&orderId=123456&apiKey=PartnerApiKey&format=json&sig nature=Signature
MediaNet Digital Confidential Page 38 of 69
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 Name Description Required? Default Value Type In the Query String... ApiKey Partner's API key. Yes String Method The name of the method to invoke. Yes String CartId The Id for the cart to purchase. Yes Integer Format The format the response should be in, No XML String JSON or XML. (Values: XML, JSON) Signature All other query string parameters in Yes String an HMAC-MD5 hash. The Partner's Shared Secret is the key. UserDomain The domain or host name (site) where Yes. String the sale originated from. 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 Yes String US is supported). 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 Yes String dashes). Cards supported are Visa, MC, Amex, and Discover. CVV The credit card security number (also Yes String known as CVV2 number).
MediaNet Digital Confidential Page 39 of 69
CardType The type of credit card. Yes String Values: • Visa • Mastercard, MC • AmericanExpress, Amex • Discover (all case-insensitive) 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&ApiKe y=PartnerApiKey&format=JSON&signature=Signature
Body of POST: { "FirstName": "John", "LastName": "Smith", "EmailAddress": "[email protected]", "BillingAddress": { "AddressLine1": "2401 Elliott Ave", "AddressLine2": "Suite 300", "City": "Seattle", "State": "WA", "PostalCode": "98121", "Country": "US" }, "CreditCard": { "FirstName": "John", "LastName": "Smith", "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&ApiKe y=PartnerApiKey&format=XML&signature=Signature
Body of POST: ÎNote the case of the elements
MediaNet Digital Confidential Page 40 of 69
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: Name Description Required? Default Value Type In the Query String... ApiKey Partner's API key. Yes String Method The name of the method to invoke. Yes String CartId The Id for the cart that the items will be Yes Integer removed from. Format The format the response should be in, No XML String JSON or XML. (Values: XML, JSON) Signature All other query string parameters in an Yes String HMAC-MD5 hash. The Partner's Shared Secret is the key. In the POST Body... MnetId The MediaNet item identifier for track or Yes String album. ItemType The type of item being purchased. Yes String (Values: Track, Album) Format The codec of the item purchased; MP3 is Yes String the only current value supported
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=PartnerApiKey&format=JSON&signature=S ignature
MediaNet Digital Confidential Page 41 of 69
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=PartnerApiKey&format=XML&signature=Si gnature
Body of POST:
Returns: ShoppingCart; see Common Response Data Elements above
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: Name Description Required? Default Value Type In the Query String... 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, No XML String JSON or XML. (Values: XML, JSON)
MediaNet Digital Confidential Page 42 of 69
Name Description Required? Default Value Type Signature All other query string parameters in an Yes String HMAC-MD5 hash. The Partner's Shared Secret is the key. SiteDomain The host name (site) where the sale Yes String originated from. UserIP The IP Address of the end user making the Yes String purchase. Username Optional: The username of end-user to No String associate order with (must pass in a valid username that has previously been created). See asterisk-marked items immediately next. 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 Country The end-user’s country (currently only US is Yes* String supported). Items MnetId The MediaNet item identifier for track or Yes String album. ItemType The type of item being purchased. Yes String (Values: Track, Album) Format The (asset) format of the item being Yes String purchased (Values: MP3) Price The retail price collected from end-user. For Yes Double 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. Tax The amount of tax collected from end-user Yes Double 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 TotalCharge The total amount to be deducted from Yes Double Partner account. This equals the sum of whatever values appear in Price + Tax fileds above
MediaNet Digital Confidential Page 43 of 69
* 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
Example in JSON: ?method=purchase.usebalance&apiKey=PartnerApiKey&format=json&userIP=enduserIPAddress &siteDomain=domainname&signature=Signature
Body of POST: { "User": // Not required if Username parameter used (for existing user) { "FirstName": "John", "LastName": "Smith", "EmailAddress": "[email protected]", "BillingAddress": { "AddressLine1": "2401 Elliott Ave", "AddressLine2": "Suite 300", "City": "Seattle", "State": "WA", "PostalCode": "98121", "Country": "US" }, "Items": [ {"MnetID":12345,"ItemType":"Track","Format":"MP3","Price":0.99,"Tax":0.00} {"MnetID":12347,"ItemType":"Track","Format":"MP3","Price":0.99,"Tax":0.05} {"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=PartnerApiKey& format=XML&userIP=enduserIPAddress&siteDomain=domainname&signature=Signature
Body of POST: ÎNote the case of the elements
MediaNet Digital Confidential Page 44 of 69
MediaNet Digital Confidential Page 47 of 69
Returns: PurchaseUseCreditCardResults; see Common Response Data Elements above
MediaNet Digital Confidential Page 48 of 69
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. artistMnetId Artist Id used for biography for No* String artist. albumMnetId Album Id used for review for No* String album. Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) Signature All other query string Yes String parameters in an HMAC-MD5 hash. The Partner's Shared Secret is the key.
*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=Partn erApiKey&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
MediaNet Digital Confidential Page 49 of 69
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) Signature All other query string Yes String parameters in an HMAC-MD5 hash. The Partner's Shared Secret is the key.
Example: ?method=partner.getBalance&apiKey=PartnerApiKey&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 (see: Tips for Methods That Require a POST Body above) Signature or SSL Required? Signature only.
Parameters: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. Amount Dollar amount to refill account Yes Double with Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) Signature All other query string Yes String parameters in an HMAC-MD5 hash. The Partner's Shared Secret is the key. Creditcard: note when using XML that the second "c" is lowercase FirstName First name of credit card Yes String holder. LastName Last name of credit card Yes String holder.
MediaNet Digital Confidential Page 50 of 69
Name Description Required? Default Value Type Number Credit card number (no spaces Yes String or dashes). Cards supported are Visa, MC, Amex, and Discover. CVV The credit card security Yes String number (also known as CVV2 number). CardType The type of credit card. Yes String Values: • Visa • Mastercard, MC • AmericanExpress, Amex • Discover (all case-insensitive) 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 Yes String address. AddressLine2 Additional address line. Yes String City The end-user’s city. Yes String State The end-user’s state (2 letter Yes String code). PostalCode The end-user’s postal code. Yes String Country The end-user’s country Yes String (currently only US is supported).
Example in JSON: ?method=partner.refillBalance&apiKey=PartnerApiKey&format=json&Amount=100.00&signature= Signature
Body of POST: { "Creditcard": { "FirstName": "First", "LastName": "Last", "Number": "4111111111111111", "CVV": "000", "CardType": "Visa", "ExpirationMonth": "5", "ExpirationYear": "2009", "Address": { "AddressLine1": "2401 Elliott Ave.", "AddressLine2": "Suite 300", "City": "Seattle", "State": "WA", "PostalCode": "98121", "Country": "US" } } }
MediaNet Digital Confidential Page 51 of 69
Example in XML: ?method=partner.refillBalance&apiKey=PartnerApiKey&format=xml&Amount=100.00&signature= Signature
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: Name Description Required? Default Value Type ApiKey Partner's API key. Yes String Method The name of the method to Yes String invoke. Ascending Sort direction. No Ascending Boolean EndDate The ending date to return order Yes String history for. Format The format the response should No XML String (Values: be in, JSON or XML. XML, JSON) Page The page number that should No 1 Int be retrieved. PageSize The number of items per page. No 5 Int
MediaNet Digital Confidential Page 52 of 69
Name Description Required? Default Value Type Signature All other query string Yes String parameters in an HMAC-MD5 hash. The Partner's Shared Secret is the key. SortType Field to sort the report by. No Orderdate String Options include: • FirstName • LastName • OrderID • OrderDate • OrderStatus • PaymentAmount • PaymentStatus StartDate The starting date to return order Yes String history for. Username* The user to get order history Yes* String for.
*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=PartnerApiKey& page=1&pageSize=10&userID=userID&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
MediaNet Digital Confidential Page 53 of 69
Use Cases
The following section details the recommended sequences of steps to accomplish tasks via the MN Open API: • 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 Login o View/Display User Details o Set (change) a User's Password o Update (change) a User's Details
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)
MediaNet Digital Confidential Page 54 of 69
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 "&".)
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.
Login DEPRECATED 1. Call User.Login with UserID and password 2. On success, an Auth Token is returned, which you should store for use in subsequent User methods 3. Note: there is no Logout method.
MediaNet Digital Confidential Page 55 of 69
View/Display User Details 1. Prerequisites: 1. The user must exist; it not, call User.Create (see above) 2. The user must be logged in; call User.Login (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. The user must be logged in; call User.Login (see above) 2. Call User.Update with, at minimum, the username and at least one other item to be changed.
MediaNet Digital Confidential Page 56 of 69
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%
MediaNet Digital Confidential Page 57 of 69
Appendix B: Label Owners by Identifier and Name
The following table was current through July 23, 2009. In the future this information will be exposed via API for programmatic consumption.
The ID column corresponds to the LabelOwnerId element in Search Package responses.
NO# CORP_CODE ID LABEL_OWNER_NAME 1 K7R 395 !K7 Records 2 TWL 149 1201 Music 3 2DG 490 2DOGS Records 4 2P9 314 2point9 Records 5 4RB 315 4 Real Records And Red Balloon Records 6 972 28 972 Records 7 ATE 23 A-Train Entertainment 8 ABR 316 Ability Records 9 ABT 54 ABT Music 10 ACE 303 Ace Records 11 ACM 597 ACM Records 12 ACN 548 Acony Records 13 ACR 528 Acorn Music 14 ABM 239 Ad Bradley Music 15 ADM 317 Adage Music 16 AHI 232 Ahi-Nama Music 17 AIR 196 Ai Records 18 ARS 494 Airstrip 19 ALP 885 Alien Productions 20 ALL 116 All Arc Enterprises, Inc. 21 ALG 51 Alligator Records 22 APR 493 Alpha Pup Records 23 ABL 318 Alternative Blueprint Records 24 AML 667 Amalgam Entertainment LLC 25 AMA 615 Amato Distribution 26 AMC 319 Amber Cafe 27 AJN 475 Anjunabeats Records 28 ANT 185 Anthem Records 29 AJX 320 Apple Jaxx UK 30 ARD 61 Ardent Music 31 ARH 259 Arhoolie 32 ARK 41 ArkMusic 33 ARO 519 Artists Only LLC 34 AAC 477 Arts and Crafts 35 API 516 Artspages International 36 BEE 55 Audio Bee 37 APP 186 Autopilot Publishing 38 AVB 508 Average Bear Records 39 AWL 182 Awal 40 BNY 150 Baby New Year Music 41 BCB 210 Bacci Bros Records 42 BTR 547 Bad Taste Records 43 BEF 601 Barraka El Farnatshi Productions
MediaNet Digital Confidential Page 58 of 69
NO# CORP_CODE ID LABEL_OWNER_NAME 44 BAS 57 Basileus Music 45 BBC 572 BBC Audiobooks Ltd. 46 BCM 190 Because Music 47 BEG 166 Beggars Group 48 BFR 634 Believe FR 49 BEU 321 Bella Union 50 BBL 322 Benbecula Limited 51 BGS 221 BGS Productions Ltd 52 BDM 504 Big Daddy Music Distribution 53 BFM 122 Big Fish Media 54 BIM 502 Big Machine 55 BTV 237 Big Time TV 56 B/W 323 Black And White 57 BLR 325 Blackend Records 58 BLW 326 Blow Up Records 59 BBK 327 Blue Black 60 BLU 21 Blue Canoe 61 BMG 4 BMG 62 BGI 85 BMG International 63 BCS 328 Botchit And Scarper 64 BMI 6 Brentwood 65 BSD 665 Broadstreet Digital 66 BUZ 329 Buzz 67 BZF 330 Buzzin Fly Records 68 CAD 117 Cadiz Digital 69 CAJ 311 Cajual Entertainment 70 CAM 331 Camino Records 71 CLR 332 Candlelight Records 72 CAZ 92 CanZion Group 73 CAS 99 Casablanca Publishing 74 CAT 722 Catapult Distribution 75 CAY 333 Cayenne Recordings 76 CCE 685 CC Entertainment 77 CDB 29 CDBaby 78 CEN 97 Centaur Records 79 CNT 334 Centric Records 80 CRR 335 Cherry Red 81 CHM 496 Chime Entertainment 82 CSL 336 City Slang 83 CPR 230 Compadre Records 84 CON 84 Concord Records 85 CIM 107 Consolidated Independent Music 86 AZU 262 Cool Pool 87 COF 341 Country Fire 88 CR2 342 Cr2 Records Ltd 89 CRT 343 Cr2 Trax 90 CSS 344 Crash Records 91 CRZ 345 Craze Productions 92 CRS 37 Crescendo 93 CMR 346 Critical Mass Records 94 CRB 81 Curb Records 95 CRL 265 Curb Records Ltd
MediaNet Digital Confidential Page 59 of 69
NO# CORP_CODE ID LABEL_OWNER_NAME 96 CRV 702 Curve Music 97 CUT 573 Cutting Records 98 CYP 865 CYP Limited 99 DCM 824 Da Capo Music 100 MTU 595 deeep.net/MTunes Digital Distribution 101 DSR 347 Deeper Substance Records 102 DMG 499 Demon Music Group 103 DIC 348 Dicelines Records 104 DGR 88 Diggin Dog Records 105 DGQ 509 digiClique 106 DHR 349 Digital Hardcore 107 DMM 312 Digital Music Marketing 108 DMI 112 Digital Musicworks International 109 DRA 32 Digital Rights Agency 110 DGP 74 Digitalpressure 111 DWX 666 Digiwaxx LLC 112 DCI 178 Disc Imports 113 DIS 124 Distort Entertainment 114 DMR 20 DM Records 115 DOG 228 Dog London 116 DME 350 Dome 117 DEI 569 Dominion Entertainment, Inc. 118 DNA 305 Domino North America 119 DOM 115 Domo Records 120 DOR 171 Dorado 121 DPP 201 Dotpointperiod 122 DBS 351 Double Snazzy 123 DKE 35 Doyle-Kos Entertainment 124 DRC 238 Drag City 125 DRM 187 Dramatico Entertainment 126 DTP 352 DTPM Recordings 127 DTX 353 DTRAX Recordings 128 DUT 95 Dualtone Music Group 129 DUR 354 Dune Records 130 ERC 16 Eagles Recording Company 131 ECO 202 Echo 132 EDN 604 Edelnet GMBH 133 EDG 355 Edge Records 134 EGM 234 Egami Media 135 ESL 100 Eighteenth Street Lounge Music 136 EMI 2 EMI 137 EMC 605 EMI Music Canada 138 EMU 356 Emubands 139 EML 73 Emusiclatino 140 EPU 170 Epitaph UK 141 EPM 825 ePM Online 142 EMS 313 Equity Music Service 143 ERR 357 Erase Records 144 ESP 36 ESP Disk' 145 EVR 473 Ever Records 146 EXR 209 Exceptional Records 147 EXC 358 Excited
MediaNet Digital Confidential Page 60 of 69
NO# CORP_CODE ID LABEL_OWNER_NAME 148 EMD 592 Executive Music Distribution 149 FAB 359 FABSmusic 150 FAN 14 Fantasy 151 FAR 19 Farfield Records 152 FFX 360 Fat Fox Records Ltd 153 FNE 27 Favored Nations 154 FAX 264 FAX +49-69/450464 155 FIN 173 Finetunes 156 FLV 361 Flamencovision 157 FLR 208 Flashlight Records 158 FFG 510 For Future Generations Inc. 159 FDM 985 Foundation Media 160 420 362 Four Twenty Recordings 161 FOX 525 Foxy Melody 162 FSQ 363 Freshly Squeezed Music 163 GCL 364 G-Club Music 164 GEI 365 Geist Records 165 GEN 614 Generika.com 166 GTR 192 Genius Twin Recordings 167 GLZ 366 Glaze Recordings 168 GLU 762 Global Underground 169 GWR 367 Global Warming 170 GLB 476 Globe Star Recordings 171 GLF 368 Golf Records 172 GOR 369 Gorgeous Music 173 GRD 63 Gourd Music 174 GRM 371 Greenroom Digital 175 GRN 372 Gronland Ltd. 176 GVA 659 Groove Attack GmbH 177 GRV 474 Groovesource 178 GUT 309 Gut Records 179 HKP 373 Hackpen 180 HSD 374 Hayseed Dixie Records 181 HET 375 Heat Recordings Ltd 182 HVR 376 Heavy Rotation 183 HFT 514 Hefty Records 184 HLR 377 Hi Life Records 185 HBR 261 Hidden Beach Recordings 186 HDM 378 High Desert Music 187 HIT 64 Hitchcock Media 188 HMV 172 HMV 189 HOL 38 Hollywood Records 190 HOR 379 Hope Recordings 191 HOS 380 Hospital Records 192 HPT 381 Hot Pot 193 HOT 197 Hot Records 194 HUR 382 Human Recordings Ltd 195 HUN 560 Hungama 196 HYB 111 Hybrid Recordings 197 IAM 662 I Am Music Online 198 ICE 383 Ice Cream Records 199 IDE 83 IDEA Distributors
MediaNet Digital Confidential Page 61 of 69
NO# CORP_CODE ID LABEL_OWNER_NAME 200 IDR 151 Idol Records 201 IFZ 82 iFanz Records 202 ISR 384 Illa State Records Ltd. 203 IMR 385 Immortal Records 204 INM 386 In Music 205 INP 387 In Promo 206 IND 15 Independent 207 IDA 905 Independent Digital Licensing Agency 208 IYO 145 Indeyo Records 209 ING 44 INgrooves 210 IGO 486 Inigo Recordings 211 IPM 58 Inner Peace Music 212 ISM 76 Inside Music Inc. 213 IRL 389 Interesting Renascent Ltd 214 ITG 388 Intergral Records 215 IOM 501 iO Music 216 IOD 70 IODAlliance 217 IRI 71 IRIS Distribution 218 JAM 206 Jam Central Records 219 JDR 1005 Jamdown Records 220 JEP 390 Jeepster 221 JMY 492 Jenna Myles 222 JET 283 Jet Star 223 JPM 596 John Parr Music Ltd. 224 JSP 391 JSP 225 JGL 392 Jungle 226 JRR 393 Junior Records 227 JUS 394 Just Music 228 KFD 268 K-Fed Productions Inc. 229 KMG 513 Kajmere Music Group 230 KFM 396 KFM 231 KIS 225 Kissy Music 232 KWR 397 Kitchenware 233 KDL 945 Kobalt Digital Licensing 234 KCD 286 Koch Distribution 235 KOC 101 Koch Records 236 KTR 148 Kontor New Media 237 KRZ 223 Kriztal Entertainment 238 KDT 398 Ku De Ta Music 239 KUD 194 Kudos Records ltd. 240 KUF 113 KUFALA Recordings 241 LCD 606 La Central Digital 242 LAC 588 La Cupula Music 243 LWL 1025 Label Worx Limited 244 LAS 487 Lasky Records 245 LCR 263 Latin Cool Records 246 LCM 224 Licensemusic.com 247 LMR 600 Lightning Man Records 248 LJO 123 Lil' Joe Records 249 LDR 479 Little Dog Records 250 LLR 24 LLR Gospel Music 251 LPM 399 LPMusic
MediaNet Digital Confidential Page 62 of 69
NO# CORP_CODE ID LABEL_OWNER_NAME 252 LJD 87 Lumberjack Distribution 253 M2K 802 M2K Music & Media 254 MMA 400 MA Music Art 255 MAD 518 Madacy 256 MAL 401 Maelstrom 257 MAG 65 Maggie's Music 258 MGE 402 Magick Eye 259 MLG 593 Malligator 260 MRP 403 Marine Parade 261 MPD 413 Massproduktion 262 MAT 235 Matador Records 263 MAV 13 Maverick 264 MBD 845 Mbop Direct 265 MGD 414 Mbopglobal-Delta 266 MED 415 Media Records 267 MBG 416 Megabop Global-Prestige Elite Records 268 MPI 204 Memphis Industries 269 MEM 25 Memphis International 270 MRC 531 Mercury Music Prize Ltd 271 MRG 524 Merge Records 272 MES 119 Messenger Records 273 MBR 198 Metal Blade Records 274 Mi5 417 Mi5 Recordings Uk 275 MOS 168 Ministry Of Sound 276 MFR 567 Minty Fresh 277 MMP 285 Miss Moneypenny 278 MNE 418 Mnemonics Music 279 MOB 419 Mob Records 280 MMD 656 Modern Media Distribution 281 MOM 195 MOMT Records 282 MOR 98 Mordam Records 283 MPR 308 Morphius Records 284 MRR 500 Morr Music 285 MSH 420 Moshi Moshi 286 MAC 603 Mountain Apple Company 287 MVS 421 Movementinsound 288 MSL 498 Moving Shadow Ltd 289 MSI 108 MSI Music Corp 290 MTV 78 MTV Networks 291 MRK 422 Murk Records/Murk Classics 292 MDL 546 Musicdld.com 293 RRT 86 Musicindie & Association of Independent Music 294 MJM 566 MusicJustMusic 295 MNT 11 MusicNet 296 NWS 1085 N.E.W.S. NV 297 NAC 478 Nacional Records 298 NAT 17 Native Language Music 299 NAV 503 Navarre 300 NAX 79 Naxos 301 NEB 423 Nebula 302 NTA 53 Nettwerk America 303 NTP 52 Nettwerk Productions
MediaNet Digital Confidential Page 63 of 69
NO# CORP_CODE ID LABEL_OWNER_NAME 304 NDR 661 Neurodisc Records 305 NSE 424 New State Entertainment 306 NWM 72 New World Music 307 NMS 425 Ninemuse 308 NTR 105 Nitro Records 309 NBM 199 NorthernBlues Music 310 NUR 1045 Nu Urban 311 NUD 485 Nude Records 312 NMG 66 Nuendo Music Group 313 OBY 527 Oh Boy Records 314 OMR 683 Om Records 315 OLI 80 One Little Indian Ltd 316 OUK 495 One Little Indian UK 317 OPF 310 Opus Fromus 318 ORR 426 Orient Recordings 319 ORV 89 Orville Records 320 OSE 663 Oseao Inc. 321 OTA 62 Ota Records 322 P3M 427 P3 Music 323 PAC 554 Pacific Art 324 PLM 42 Palm Records 325 PNW 266 Panartist Networks 326 PAN 193 Pandisc 327 PRU 428 Pangea Recordings UK 328 PAR 682 Paramount Digital Entertainment 329 PER 429 Pear Music 330 AAO 146 Peter Kuys AAO Music 331 PWK 179 Pickwick International Limited 332 PIR 430 Picnic Records 333 PIN 181 Pinnacle Records 334 PEC 571 Planet E Communications 335 PLR 431 Plastic Raygun 336 PRM 96 Priddis Music 337 PAM 553 Pro-Active Music Ltd 338 PMD 180 Proper Music Distribution 339 PTS 511 Protest Recordings 340 PCB 91 Psychobaby 341 PLS 481 Pulse Rated Music 342 PRC 432 Purple City 343 QIN 120 Quinlan Road 344 R2R 433 R2 Records 345 RAN 121 Ranbach Music Ltd. 346 RLP 68 Ray Lynch Productions 347 RAZ 60 Razor & Tie 348 RMU 39 Real Music 349 RBD 657 Rebeat Digital GmbH 350 REB 489 Rebel Records 351 RMI 658 Rebelmix Inc. 352 RBT 67 Reboot Music 353 RCL 306 Recall Records 354 RNT 233 Red Antenna 355 RED 31 Red Distribution
MediaNet Digital Confidential Page 64 of 69
NO# CORP_CODE ID LABEL_OWNER_NAME 356 RDY 50 Redeye Inc. 357 RFR 69 Refined Records 358 RFM 441 Reform Recordings 359 GCM 103 Reincarnate Music 360 REV 236 Revolver Music Limited & Heavy Metal Records Limited 361 RBR 472 Righteous Babe Records 362 RCM 506 Riotclub Music 363 RBP 517 RipBurnPlay Records 364 RIT 10 Ritmoteca 365 RVS 442 Riverside 366 RRI 324 Roadrunner International BV 367 RRR 43 Roadrunner Records 368 ROB 443 Robot Records 369 RSG 557 Rockstar Games 370 RCS 444 Rocstar Recordings 371 ROS 47 Roswell Records 372 RTR 497 Rough Trade Records Limited 373 RND 33 Rounder 374 RSK 664 RSK Entertainment Ltd. 375 RSD 200 Rustic Digital 376 RYM 445 Ryder Music 377 RYO 106 Rykodisc 378 SCR 109 Saddle Creek Records 379 SAM 654 SAMPLE 380 SAN 9 Sanctuary 381 SUK 165 Sanctuary UK 382 SKM 925 Sandy Key Music 383 SAV 102 Savoy 384 SCL 446 Scarlet Recordings 385 SER 447 Scenario Records 386 SCA 448 Seeca 387 SED 559 Seed Records 388 SEG 449 Segment Records 389 STR 450 Sentient Records 390 SEQ 26 Sequoia Records 391 SGR 451 Seriously Groovy Music Ltd 392 SHK 483 Shark Meat Records 393 SHA 532 Shashamane Movement 394 SHD 452 Shed Records 395 ART 174 Sheridan Square Entertainment 396 S1D 48 SideOneDummy Records 397 SNS 219 Simon & Schuster 398 SIX 59 Six Degrees Records 399 SKT 453 Skint Records 400 SKY 454 Skyline 401 SLR 455 SL Records 402 SLV 456 Slinding Vinyl 403 SMK 457 Smekkleysa SM 404 SMG 189 Smith Music Group 405 SNP 458 Snapper Music Pic 406 SMA 459 Soma 407 SUR 482 Sonic Unyon Records
MediaNet Digital Confidential Page 65 of 69
NO# CORP_CODE ID LABEL_OWNER_NAME 408 SON 110 Sonic360 409 SME 3 Sony Music 410 SMC 118 Sony Music Canada 411 SMI 114 Sony Music International 412 SPE 684 Sony Pictures Entertainment 413 SSP 822 Soulspazm Records 414 SCK 90 Sound Choice Karaoke 415 SOP 77 Soundings of the Planet 416 SOU 183 Southern Records 417 SPA 488 spinART Records 418 SPR 460 Springthyme Records 419 SPV 480 SPV Gmbh 420 STK 461 Startracks 421 S51 167 State 51 422 STW 176 Stones Throw Records 423 STB 222 StreetBeat Records 424 STU 304 Studio Distribution 425 SUB 40 Sub Pop 426 SCM 589 Subconscious Music 427 SMR 484 Submerge Recordings 428 SUN 191 Sunnyside Communications 429 SLG 782 Sunset Label Group 430 EGO 307 Superego Records 431 SYN 220 Synergie Logistics 432 SYD 598 Syntax 433 SYR 591 Syntax Distribution 434 TAK 188 Takeout Records 435 TAS 462 Taste Media 436 TEL 594 Telarc Records 437 TEM 602 Tempo Tantrum 438 TEO 599 Teoleindy Music Group 439 TMG 104 Texas Music Group 440 TAG 22 The Aradia Group 441 ORC 18 The Orchard 442 TRP 570 The Relief Project, LLC 443 WLK 284 The Welk Group 444 THR 565 Thirsty Ear 445 TJR 260 Thrill Jockey 446 TID 231 tidbit music 447 TWP 207 Timewarp Distribution 448 TNY 463 Tiny Dog 449 TMY 94 Tommy Boy Entertainment 450 TCE 93 Toucan Cove Entertainment 451 TGO 177 Touch And Go Records 452 TCO 551 Tough Cookie 453 TRU 30 Tried & True Music 454 TUM 515 TUMI Productions 455 TUN 491 Tunecore 456 TVT 184 TVT Records 457 UMG 5 Universal 458 UPB 464 Upbeat Records 459 UPL 226 Uploader
MediaNet Digital Confidential Page 66 of 69
NO# CORP_CODE ID LABEL_OWNER_NAME 460 UGR 587 Urban Gospel Records 461 V2R 45 V2 Records 462 V2I 465 V2 Records International 463 V2S 466 V2 Scandinavia 464 V2U 467 V2 UK 465 VGR 46 Vagrant Records 466 VAR 205 Van Richter Records 467 VAN 49 Vanguard Records 468 VIC 75 Victory Records 469 VRL 203 Virtual Label LLC 470 VIT 147 Vital PIAS Digital 471 WLR 468 Wallop Recordings 472 DHE 823 Walt Disney Studios Home Entertainment 473 WAR 556 Warlock Records 474 WMG 1 Warner 475 WAP 175 Warp Records 476 WAT 965 WaTunes 477 WNR 471 West Nile Records 478 WSF 469 West Side Fabrication 479 WES 34 Western Music Network 480 HOG 56 Whole Hog 481 WCT 470 Wichita Recordings 482 WPM 549 Wild Palms Music 483 WUP 526 Wind-Up Records 484 WHR 512 Woodhill Records 485 WCR 545 World Circuit 486 WMO 552 World Music Office 487 WLD 616 WorldSound, LLC 488 WRT 227 Wretched Recordings 489 X5M 617 X5 Music 490 XBR 742 XIII Bis Records 491 YZU 763 Yuzu Music 492 ZBL 505 Zebralution GMBH 493 ZOJ 660 Zojak World Wide 494 ZRC 7 Zomba
MediaNet Digital Confidential Page 67 of 69
Appendix C: 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
MediaNet Digital Confidential Page 68 of 69
• 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.
MediaNet Digital Confidential Page 69 of 69