JunoAPI SEARCH v1.3.1

1
JUNO SEARCH API

REFERENCE DOCUMENT
Version 1.2.2

2

Table of Contents

1 Juno API ...................................................................................................................... 4
1.1 Versioning ............................................................................................................... 4
1.2 Authentication ......................................................................................................... 4
1.3 Parameters ............................................................................................................. 4
1.4 HTTP Status Codes ................................................................................................ 4
1.5 Error Messages ...................................................................................................... 5
1.6 Encoding ................................................................................................................. 5
2 Data API ....................................................................................................................... 6
2.1 General Use............................................................................................................ 6
2.1 Territory Restrictions ............................................................................................... 6
2.2 Product pricing ........................................................................................................ 6
2.3 Data API Object Model ........................................................................................... 7
2.4 Track.getList ........................................................................................................... 7
2.5 Track.getDetails ...................................................................................................... 9
2.6 Bundle.getList ....................................................................................................... 11
2.7 Bundle.getDetails .................................................................................................. 14
3 Reference API ............................................................................................................ 17
3.1 Reference.getGenres() ......................................................................................... 17
3.2 Reference.getFormats() ........................................................................................ 17
3.3 Reference.getCountries() ...................................................................................... 18
3.4 Reference.getCurrencies() .................................................................................... 19
3.5 Reference.getOrderStatuses() .............................................................................. 19
4 Media Links ................................................................................................................ 21
4.1 MP3 Preview ......................................................................................................... 21
4.2 Cover Image Thumbnails ...................................................................................... 21
5 Affiliate Links ............................................................................................................. 21
5.1 Information Page - Track....................................................................................... 21
5.2 Information Page Album/Single .......................................................................... 21
6 Caching ...................................................................................................................... 22
7 Feed Export ............................................................................................................... 22
7.1 Full snapshot ........................................................................................................ 22
7.2 Incremental snapshot Deleted bundles .............................................................. 24
7.3 Incremental snapshot Updated bundles ............................................................. 26
7.4 Incremental snapshot New bundles ................................................................... 27
8 Implementation Checklist ......................................................................................... 29
9 Exceptions and error handling ................................................................................. 30
9.1 Error codes ........................................................................................................... 30
10 Appendix A - Objects ................................................................................................ 32
10.1 Track ................................................................................................................. 32
10.2 Artist .................................................................................................................. 33
10.3 Format ............................................................................................................... 33
10.4 Bundle ............................................................................................................... 33
10.5 Bundle Track ..................................................................................................... 34
10.6 Genre ................................................................................................................ 34
10.7 Country ............................................................................................................. 35
10.8 Currency............................................................................................................ 35
10.9 Format_price ..................................................................................................... 35
10.10 Country_price .................................................................................................... 36

3

History

Date Version Updated by Description
2009-12-09 1.2.0 Julien Etter - Attributes used for pagination when relevant
- Attributes used for order status
- Enforce non-empty response for every call
- Object definition/samples tidied up
2009-12-17 1.2.0 Julien Etter - Doenableorderitem parameters updated
2010-01-07 1.2.0 Julien Etter - Added customer_post_code as mandatory for
country_iso_code=GB
2010-01-26 1.2.0 Julien Etter - Changed Order.getHistory and
Order.getCurrentDownloads not to include
order_files.
1.2.0
2010-02-01 1.2.1 Julien Etter - Snapshot and incremental feeds added
2010-03-17 1.2.1 Julien Etter - Added class based criteria for bundle search
2010-03-23 1.2.1 Julien Etter - Added index.csv
2010-05-25 1.2.2 Julien Etter - Optional country in
bundle/tracks.getlist/getdetails
- New format_prices node
2010-06-09 1.2.3 Julien Etter - New format price node

4

1 Juno API
The Juno API attempts to conform to the design principles of Representational State
Transfer (REST).

All Juno API requests should be http POST request and responses are all currently in XML
format based on the Juno object model.
1.1 Versioning
The current major version of the API is 1.2, revsion 2.

We will update the minor version of the API and this reference document whenever a non-
destructive change happens, ie the change doesn not impact the current XML model,
making sure your implementation of the API doesnt break over a minor verrsion change.
In this case, we will contact you a few days before our planned update to insure continuity of
service.

The major version will be changed whenever a change in the object model/XML is
considered as destructive, ie the change may affect your inplementation of the system.
In this case we will contact you 2 to 3 month before our planned update.
1.2 Authentication
Accessing the Juno API requires the use of a private key which identifies you as a user.
When applying for an API key, the IP address of the API consumer must also be submitted;
API requests will only be allowed from that IP address.
The key provided to you should be kept confidential at all times. Without a valid key, API
requests will not be fulfilled.
1.3 Parameters
All API methods take mandatory and optional parameters in the form of POST request
parameters.
1.4 HTTP Status Codes
The Juno API attempts to return appropriate HTTP status codes for every request. Here's a
list of various status codes currently in use:
200 OK: everything went well.
304 Not Modified: there was no new data to return.
400 Bad Request: your request is invalid, probably because an invalid parameter was used
or you have exceeded your rate limit. Well return an error message that tells you why your
request was invalid.
401 Not Authorized: either you need to provide authentication credentials (key), or the
credentials provided aren't valid.
403 Forbidden: we understand your request, but are refusing to fulfill it. An accompanying
error message should explain why.
404 Not Found: either you're requesting an invalid URI or the resource in question doesn't
exist.

5

1.5 Error Messages
When the Juno API returns error messages, it does so in XML format in the form of an error
object.
See details on Exceptions and error handling

As well as the error object returned, the HTTP reponse headers can also be used to detect
errors.

1.6 Encoding
The Juno API supports UTF-8 encoding. When requesting XML, the response is UTF-8
encoded. Symbols and characters outside of the standard ASCII range may be translated to
XML entities.

6

2 Data API
2.1 General Use
The data API can be used to retrieve information about tracks and bundles currently for sale
at Juno. POST parameters can be combined when performing API requests, allowing a
flexible system of retrieving results.

For example, to get the top selling tracks of 2009, your request would be a POST request to
http://www.junodownload.com/api/track/getlist/ with the following variables:

key = 4e6b6f87083facc7fa804f72a46bff22
release_date_start = 1230768000
sort_by = bestselling
sort_direction = desc

2.1 Territory Restrictions
All the data API calls have an optional parameter of an country ISO code. This is used to
restrict the information returned to only bundles/tracks which are available in the end users
country.

If the country ISO code is not included as a parameter the API will default to using UK as the
country code and only return information relevant to UK customers.

2.2 Product pricing
When calling bundle.getlist, bundle.getdetails, track.getlist or track.getdetails, recommended
pricing information can be found in the format_prices node.
The price displayed applies to the country parameter being sent, GB being the default if
none is sent.
The bundle and track prices are always in GBP currency.

<format_prices>
<format_price>
<format_id>1</format_id>
<currency_code>GBP</currency_code>
<amount>1.99</amount>
</format_price>
...
</format_prices>

Through the Feed export (full or incremental snapshot), extra country_prices node indicates
the price of the bundle/track per country, using the local currency.
<format_prices>
<format_price>
<country_prices>
<country_price>
<country_code>US</country_code>
<currency_code>USD</currency_code>
</country_price>

7

<country_price>
<country_code>FR,AT,CY,FI</country_code>
<currency_code>EUR</currency_code>
</country_price>
...
</country_prices>
</format_price>
...
</format_prices>

2.3 Data API Object Model
-title_id
-product_id
-formats
-title
-artist
-label
-genre_id
-cat_no
-release_date
-bundle_tracks
bundle
-title_id
-product_id
-track_id
-formats
-cat_no
-bundle_title
-bundle_artists
-bundle_mirror_artists
-label
-track_title
-track_mix_title
-track_mix_artist
-track_genre_id
-release_date
-track_length
track
-id
-type
-bit_rate
format
-track_id
-track_title
-track_mix_title
-track_mix_artist
-track_genre_id
-track_length
-individual_sale
bundle_track
-bundle
bundles
-format
formats
-track
tracks
-artist
artists

2.4 Track.getList
The track getList method encompasses all the functionality required to produce a list of data
for individual tracks. This data can be filtered or sorted in any manner in which it can be on
the Juno web sites including providing full text search capabilities and sorting by bestseller.

The pricing information returned depends on the country parameter sent. Each format of
the track will have its price. The currency used will always be GBP.

Request Format

Property Type Mandatory /
Optional
Description
key String M API key provided by juno
search_type String O The column the search query should be
looked for. (all, title, artist, label)
query String O Name of track, or other keyword(s) to search
for.

8

genre #### O Restrict results to tracks in this genre. Can be
1 to 4 digits: digits 1-2 are considered the
genre ID, digits 3-4 are considered the
subgenre ID. Zero padding should be used
when IDs are less than 10 e.g. 0802 (see full
genre list)
release_date_start Int O Show only tracks released after this date
(epoch timestamp).
release_date_end Int O Show only tracks released before this date
(epoch timestamp).
page Int O Used to specify which page of a multipage
resultset should be returned.
items_per_page Int O Used to specify the number of results to be
returned. (works in combination with page to
allow pagination of results) Min/Default value
= 5, Max value = 500.
sort_by String O The column to sort the results by. (title, artist,
label, date_released, bestselling,
bestselling_week, bestselling_8weeks,
bestselling_6months)
sort_direction String O Sort direction when sorting results.
(asc, desc)
country String O ISO Code of the country the data is being
requested for. If none, the default country is
GB

Example Request:

POST: http://www.junodownload.com/api/1.2/track/getlist

key = abcdefghijklmnopqrstuvwxyz123456
sort_by = date_released
sort_direction = desc
query = juno
country= US

Response Format
-title_id
-product_id
-track_id
-formats
-cat_no
-bundle_title
-bundle_artists
-label
-track_title
-track_mix_title
-track_mix_artist
-track_genre_id
-release_date
-track_length
track
-id
-type
-bit_rate
format
-format
formats
-track
tracks
-artist
artists

See: [TRACK OBJECT], [FORMAT OBJECT], [ARTIST OBJECT], [FORMAT_PRICES
OBJECT]

9

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<tracks>
<track>
<title_id>1476292</title_id>
<product_id>2</product_id>
<track_id>2</track_id>
<formats>
<format>
<id>1</id>
<name>mp3</name>
<bit_rate>320</bit_rate>
</format>
...
</formats>
<format_prices>
<format_price>
</format_price>
...
</format_prices>
<cat_no>ng 068</cat_no>
<bundle_title>is it me</bundle_title>
<bundle_artists>
<artist>forbes, daniel</artist>
...
</bundle_artists>
<bundle_mirror_artists>
<artist>daniel forbes</artist>
...
</bundle_mirror_artists>
<label>neurotic groove</label>
<track_title>is it me</track_title>
<track_mix_title>bruze dangelo mix</track_mix_title>
<track_mix_artist>daniel</track_mix_artist>
<track_genre_id>1508</track_genre_id>
<release_date>1255651200</release_date>
<track_length>473</track_length>
</track>
...
</tracks>
<pagination>
<total_results>4659</total_results>
<total_pages>4659</total_pages>
<current_page>1</current_page>
</pagination>
</response>

2.5 Track.getDetails
The getDetails method will produce information about a single track similar to track.getList
the main difference is that getDetails will never return more than ONE result.

10

the track will have its price. The currency used will always be GBP.

Request Format

Optional
Description
title_id Int M The title ID of the track
product_id Int M Product ID of the track which is always 2.
The available product IDs may be extended
in the future. This parameter is currently
included so that no service schema changes
will be required for these changes.
track_id Int M The track ID
requested for. If none, the default country is
GB

Example Request:

POST: http://www.junodownload.com/api/1.2/track/getdetails

title_id = 1455231
product_id = 2
track_id = 3
country= FR

Response Format
-title_id
-product_id
-track_id
-formats
-cat_no
-bundle_title
-bundle_artists
-label
-track_title
-track_mix_title
-track_mix_artist
-track_genre_id
-release_date
-track_length
track
-id
-type
-bit_rate
format
-format
formats
-artist
artists

See: [TRACK OBJECT], [FORMAT OBJECT], [ARTIST OBJECT] , [FORMAT_PRICES
OBJECT]

Example Response:

<response>
<track>

11

<formats>
<format>
<id>1</id>
<name>mp3</name>
</format>
<format>
<id>1</id>
<name>mp3</name>
</format>
...
</formats>
<format_prices>
<format_price>
</format_price>
...
</format_prices>
<bundle_artists>
<artist>forbes, daniel</artist>
...
</bundle_artists>
...
</track>
</response>

2.6 Bundle.getList
The Bundle getList method encompasses all the functionality required to produce a list of
data for individual bundles. This data can be filtered or sorted using different criteria,
including providing full text search capabilities and sorting by bestseller.

the bundle and the associated tracks will have its price. The currency used will always be
GBP.

Request Format

Optional
Description

12

search_type String O The column the search query should be
looked for. (all(default), title, artist, label)
query String O Name of track, or other keyword(s), to search
for.
genre #### O Restrict results to tracks in this genre. Can be
1 to 4 digits: digits 1-2 are considered the
genre ID, digits 3-4 are considered the
subgenre ID. Zero padding should be used
when IDs are less than 10 e.g. 0802 (see full
genre list)
release_date_start Int O Show only tracks released after this date
(epoch timestamp).
release_date_end Int O Show only tracks released before this date
(epoch timestamp).
page Int O Used to specify which page of a multipage
resultset should be returned.
items_per_page Int O Used to specify the number of results to be
returned. (works in combination with page to
allow pagination of results) Min/Default value
= 5, Max value = 500.
sort_by String O The column to sort the results by. (title, artist,
label, date_released, bestselling,
bestselling_week, bestselling_8weeks,
bestselling_6months)
sort_direction String O Sort direction when sorting results.
(asc, desc)
requested for. . If none, the default country is
GB
class String O Type of bundle: all, single, album.
Default: all

Example Request:

POST: http://www.junodownload.com/api/1.2/bundle/getlist

query = juno
genre = 1203
country= US

Response Format

13

-title_id
-product_id
-formats
-title
-artists
-mirror_artists
-label
-genre_id
-cat_no
-bundle_tracks
bundle
-id
-type
-bit_rate
format
-track_number
-track_title
-track_mix_title
-track_mix_artist
-track_genre_id
-track_length
-individual_sale
bundle_track
-bundle
bundles
-format
formats
-artist
artists

See: [BUNDLE OBJECT], [BUNDLE TRACK OBJECT], [FORMAT OBJECT], [ARTIST
OBJECT] , [FORMAT_PRICES OBJECT]

Example Response:

<response>
<bundles>
<bundle>
<formats>
<format>
<id>1</id>
<name>mp3</name>
</format>
...
</formats>
<format_prices>
<format_price>
</format_price>
...
</format_prices>
<title>is it me</title>
<artists>
<artist>forbes, Daniel</artist>
<artist>sagrada, joey</artist>
...
</artists>
<mirror_artists>
<mirror_artist>daniel forbes</artist>
<mirror_artist>joey sagrada</artist>

14

...
</mirror_artists>
<genre_id>1508</genre_id>
<bundle_tracks>
<bundle_track>
<bundle_track_id>1</bumdle_track_id>
<track_title>Tell Me</track_title>
<track_mix_title></track_mix_title>
<track_mix_artist></track_mix_artist>
<individual_sale>1</individual_sale>
<format_prices>
<format_price>
</format_price>
...
</format_prices>
</bundle_track>
...
</bundle_tracks>
</bundle>
...
</bundles>
<pagination>
<total_results>4659</total_results>
<total_pages>4659</total_pages>
<current_page>1</current_page>
</pagination>
</response>

2.7 Bundle.getDetails
The getDetails method will produce information about a single product similar to
product.getList the main difference is that getDetails will never return more than ONE
result.

the bundle and the associated tracks will have its price. The currency used will always be
GBP.
Request Format

Optional
Description
title_id Int M The title ID of the track
product_id Int M Product ID of the track which is always 2.
The available product IDs may be extended in
the future. This parameter is currently included
so that no service schema changes will be
required for these changes.

15

requested for. . If none, the default country is
GB

Example Request:

POST: http://www.junodownload.com/api/1.2/bundle/getdetails

title_id = 235525
product_id = 2

Response Format

-title_id
-product_id
-formats
-title
-artists
-mirror_artists
-label
-genre_id
-cat_no
-bundle_tracks
bundle
-id
-type
-bit_rate
format
-track_number
-track_title
-track_mix_title
-track_mix_artist
-track_genre_id
-track_length
-individual_sale
bundle_track
-format
formats
-artist
artists

See: [BUNDLE OBJECT], [BUNDLE TRACK OBJECT], [FORMAT OBJECT], [ARTIST
OBJECT] , [FORMAT_PRICES OBJECT]

Example Response:

<response>
<bundle>
<formats>
<format>
<id>1</id>
<name>mp3</name>
</format>
...
</formats>
<format_prices>
<format_price>

16

</format_price>
...
</format_prices>
<artists>
<artist>forbes, Daniel</artist>
<artist>sagrada, joey</artist>
...
</artists>
<mirror_artists>
<mirror_artist>daniel forbes</artist>
<mirror_artist>joey sagrada</artist>
...
</mirror_artists>
<bundle_tracks>
<bundle_track>
<format_prices>
<format_price>
</format_price>
...
</format_prices>
</bundle_track>
...
</bundle_tracks>
</bundle>
</response>

17

3 Reference API
The reference API allows the retrieval of reference information such as genres and formats.
It is highly recommended that results of the reference API be cached locally, as these
services will not be updated very often.

3.1 Reference.getGenres()
The getGenres method returns details for all the genres currently supported by Juno.

Request Parameters

Property Type Mandatory
/ Optional
Description
key String M Juno API authentication key

Example Request:

POST: http://www.junodownload.com/api/1.2/reference/getgenres


See: [GENRE OBJECT]

Example Response:

<response>
<genres>
<genre>
<id>0001</id>
<name>Breakbeat</name>
</genre>
<genre>
<id>0002</id>
<name>Techno</name>
</genre>
...
</genres>
</response>

3.2 Reference.getFormats()
The getFormats method returns a list of all the formats of products currently sold by Juno.

Request Parameters

/ Optional
Description
Key String M Juno API authentication key

Example Request:

POST: http://www.junodownload.com/api/1.2/reference/getformats

18


See: [FORMAT OBJECT]

Example Response:

<response>
<formats>
<format>
<id>1</id>
<name>wav</name>
<bit_rate>14400</rate>
</format>
<format>
<id>2</id>
<name>mp3</name>
<bit_rate>320</rate>
</format>
...
</formats>
</response>

3.3 Reference.getCountries()
The getCountries method returns a list of all the countries currently supported by Juno.

Request Parameters

/ Optional
Description

Example Request:

POST: http://www.junodownload.com/api/1.2/reference/getcountries


See: [COUNTRY OBJECT]

Example Response:

<response>
<countries>
<country>
<id>1</id>
<code>AF</code>
<name>Afghanistan (Islamic St.)</name>
</country >
<country>
<id>2</id>
<code>AL</code>
<name>Albania</name>
</country>
...

19

</countries>
</response>

3.4 Reference.getCurrencies()
The getCurrencies method returns a list of all the currencies currently supported by Juno.

Request Parameters

/ Optional
Description

Example Request:

POST: http://www.junodownload.com/api/1.2/reference/getcurrencies


See: [CURRENCY OBJECT]

Example Response:

<response>
<currencies>
<currency>
<id>1</id>
<code>GBP</code>
<name>Pound Sterling</name>
</currency>
<currency>
<id>2</id>
<code>USD</code>
<name>US Dollar</name>
</currency>
...
</currencies>
</response>

3.5 Reference.getOrderStatuses()
The getOrderStatuses method returns a list of all the order statuses currently supported by
Juno.

Request Parameters

/ Optional
Description

Example Request:

POST: http://www.junodownload.com/api/1.2/reference/getorderstatuses

20


See: [ORDER STATUS OBJECT]

Example Response:

<response>
<statuses>
<status>
<id>0</id>
<name>Processing</name>
</status>
<status>
<id>1</id>
<name>Ready to download</name>
</status>
...
</statuses>
</response>

21

4 Media Links
Bundle/Track information can be used to generate various URLs relating to the track or
bundle.

4.1 MP3 Preview
The URL for the MP3 preview of a track can be generated using the following format:
http://mp3.juno.co.uk/MP3/SF<title_id>-<product_id>-01-<track_number>.mp3
Example: http://mp3.juno.co.uk/MP3/SF1391496-02-01-03.mp3
<product_id> and <track_number> are 0 padded 2 digits numbers.
i.e.: 2 is 02, 6 is 06, 12 is 12,.

4.2 Cover Image Thumbnails
Cover image URLs can be generated using the following format:
75 X 75 Pixels:
http:// images.juno.co.uk/75/CS<title_id>-<product_id>A-TN.jpg
Example: http://images.juno.co.uk/75/CS1391496-02A-TN.jpg
150 X 150 Pixels:
http:// images.juno.co.uk/150/CS<title_id>-<product_id>A.jpg
Example: http://images.juno.co.uk/150/CS1391496-02A.jpg
<product_id> is a 0 padded 2 digits number.
i.e.: 2 is 02

5 Affiliate Links
If you are not using the sales API, the following URLs can be used to link back to the
product and track pages on junos site.
5.1 Information Page - Track
The URL for the information page of a track can be generated using the following format:
http://www.junodownload.com/products/<title_id>-<product_id>-<track_number>.htm
Example: http://www.junodownload.com/products/1391496-02-2.htm
5.2 Information Page Album/Single
The URL for the information page of the album/single for the track can be generated using
the following format:
http://www.junodownload.com/products/<title_id>-<product_id>.htm
Example: http://www.junodownload.com/products/1391496-02.htm

22

6 Caching

Responses to the data API should be cached wherever possible to improve performance of
the system. Juno caches responses for one hour where possible.

7 Feed Export
When requesting an API key to use our API, you can ask us to use our Product Feed
mechanism.
Our Feeds are based on an incremental system, that will allow you to keep the product base
up to date without having the disadvantage of processing the whole data dump every single
time.
The first time the feed will be generated, it will be a full snapshot of our product base, after
this, incremental files will be generated hourly, exporting only the changes that happened
since the last export.

You can limit what the feed is returning you by filtering per genre/subgenre as well as Label
and Distributors.
If you wish to change those filters at a later date, a new full snapshot of our product base will
be generated.

Those files will be located in a folder that will be specific to you:
http://batch.juno.co.uk/export/[ID]/, where [ID] will be given to you when applying for the feed
export.

In this folder, a file index.csv will contain all new files that need processing. The format is:
[TIMESTAMP],[FILENAME].
For instance:
1269345610,export_20100323-120010_incremental_insert_24.xml.gz
1269345610,export_20100323-120010_incremental_update_24.xml.gz
1269345610,export_20100323-120010_incremental_delete_24.xml.gz

7.1 Full snapshot
This file will be generated if needed at around midnight GMT.
Its file name will be: export_20100129-180458_snapshot_28.xml.gz
Where 20100129-180458 is the date and time the export was generated, and 28 will be your
personal [ID].
The file will be compressed using the Gnu ZIP format.

The format used corresponds to the Bundle object, a restriction node is added to it to reflect
which countries the bundle is not allowed to be sold.

Once a full snapshot has been created, incremental files will be generated once every hour.

23

-title_id
-product_id
-formats
-title
-artists
-mirror_artists
-label
-genre_id
-cat_no
-bundle_tracks
bundle
-bundle
-restrictions
Bundle_product
-country
restriction

Format:

<response>
<datadump>
<bundle_product>
<bundle>
<formats>
<format>
<id>1</id>
<type>mp3</type>
</format>
...
</formats>
<format_prices>
<format_price>
</format_price>
<country_prices>
<country_price>
</country_price>
<country_price>
</country_price>
...
</country_prices>
...
</format_prices>
<title>Exclusively</title>
<artists>

24

<artist>Andy, Horace</artist>
...
</artists>
<mirror_artists>
<artist>Horace Andy</artist>
...
</mirror_artists>
<label>Wackies Germany</label>
<cat_no>W 107LP</cat_no>
<bundle_tracks>
<bundle_track>
<bundle_track_id>1</bundle_track_id>
<track_title>Bob Lives On</track_title>
<track_mix_title />
<track_mix_artist />
<format_prices>
<format_price>
</format_price>
<country_prices>
<country_price>
</country_price>
<country_price>
</country_price>
...
</country_prices>
...
</format_prices>
</bundle_track>
...
</bundle_tracks>
</bundle>
<restrictions>
<country>CS</country>
...
</restrictions>
</bundle_product>
</datadump>
</response>

7.2 Incremental snapshot Deleted bundles
Its file name will be: export_20100129-180458_incremental_delete_28.xml.gz
personal [ID].
This file contains the list of bundles that need to be deleted.
Format:

25

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<response>
<bundle_delete>
<bundle>
</bundle>

</bundle_delete>
</response>

26

7.3 Incremental snapshot Updated bundles
Its file name will be: export_20100129-180458_incremental_update_28.xml.gz
personal [ID].
This file contains the list of bundles that need to be updated.

<response>
<bundle_update>
<bundle_product>
<bundle>
<formats>
<format>
<id>1</id>
<type>mp3</type>
</format>
...
</formats>
<format_prices>
<format_price>
<country_prices>
<country_price>
</country_price>
...
</country_prices>
</format_price>
...
</format_prices>
<artists>
...
</artists>
<mirror_artists>
...
</mirror_artists>
<bundle_tracks>
<bundle_track>
<track_mix_title />

27

<format_prices>
<format_price>
<country_prices>
<country_price>
</country_price>
...
</country_prices>
</format_price>
...
</format_prices>
</bundle_track>
...
</bundle_tracks>
</bundle>
<restrictions>
...
</restrictions>
</bundle_product>
</bundle_update>
</response>

7.4 Incremental snapshot New bundles
Its file name will be: export_20100129-180458_incremental_insert_28.xml.gz
personal [ID].
This file contains the list of bundles that need to be updated.

<response>
<bundle_insert>
<bundle_product>
<bundle>
<formats>
<format>
<id>1</id>
<type>mp3</type>
</format>
...
</formats>
<format_prices>
<format_price>
<country_prices>
<country_price>

28

</country_price>
...
</country_prices>
</format_price>
...
</format_prices>
<artists>
...
</artists>
<mirror_artists>
...
</mirror_artists>
<bundle_tracks>
<bundle_track>
<track_mix_title />
<format_prices>
<format_price>
<country_prices>
<country_price>
</country_price>
...
</country_prices>
</format_price>
...
</format_prices>
</bundle_track>
...
</bundle_tracks>
</bundle>
<restrictions>
...
</restrictions>
</bundle_product>
</bundle_insert>
</response>

29

8 Implementation Checklist

You are handling errors correctly
o i.e. do NOT continue processing if placing or finalising an order fails.
You are using 2-phase commits
o Start the order to ensure that all the products in the order are actually allowed
to be sold to the customer in that country
o Process payment
o Once payment is taken finalise the order with the Juno sales api to allow the
product downloads to be accessed.
Please set correct order status
o Test ONLY when running tests
o Normal when placing actual orders
The field amount under Order Item should contain the retail price excluding vat
Now contact Juno for the production Sales API URL.

30

9 Exceptions and error handling
When a validation error occurs in the Sales API system an error will be returned.

The error has a Detail property which contains more information about the error that has
occurred. This is populated by sales API when throwing a validation error. The detail
property is an XmlNode which has the following structure.

<errors>
<error>
<code></code>
<message></message>
<value></value>
< error >
...
<errors>

The code element refers to a predefined error code. This code refers to an
enumeration within the system.
The message element gives a description of the error that took place.
The value is an option element that gives the value that caused the error

9.1 Error codes

Error Code Description
UNKNOWN_ERROR 000 Unknown error
METHOD_NOT_SPECIFIED 001 Missing method name
UNKNOWN_METHOD 002 Unknown method
UNKNOWN_PROPERTY 003 Unknown property
INVALID_API_KEY 004 Invalid API key
INVALID_IP_ADDRESS 005 Invalid IP address
REQUEST_MUST_BE_POST 006
This API call must be made as a
POST request
MISSING_PARAMETER 007 Missing parameter
INVALID_PARAMETER 008 Invalid parameter
TRACK_NOT_FOUND 011 Track file not found
INVALID_TRACK_POSITION 012 Invalid track seek positon
ORDER_NOT_FINALISED 018 Order not finalised
TRACK_ALREADY_ADDED_IN_BUNDLE 019 Track already added in bundle
BUNDLE_NOT_AVAILABLE 021 Bundle not available
BUNDLE_COUNTRY_RESTRICTED 022 Bundle cannot be sold in the specified

31

country
TRACK_NOT_AVAILABLE 023 Track not available
TRACK_COUNTRY_RESTRICTED 024
Track cannot be sold in the specified
country
NO_ITEMS_IN_CART 025 No items were added to cart
INVALID_CUSTOMER_ID 026
UNAUTHORISED_CUSTOMER 027
Accessing this customer account is
not permitted
UNAUTHORISED_ORDER_ID 028 Processing this order is not permitted
ORDER_ALREADY_COMPLETE 029 The order has already been completed
UNKNOWN_ORDER_ID 030 Unknown order ID
FAILED_REENABLING_PRODUCT 031 Failed re-enabling product
FAILED_REENABLING_ORDER 032 Failed re-enabling order
FAILED_REENABLING_ORDERITEM 033
This item could not be found in this
order.

32

10 Appendix A - Objects
Below are formatted examples of various objects.
10.1 Track

Property Type Description
title_id Int Title ID for a track.
product_id Int Product ID for a track.
track_id Int The position of this track in its bundle.
formats [Format Object] Available formats for this track.
Format_prices [Format Price
Object]
Available recommended prices
cat_no String Catalogue number for a track.
bundle_title String Name of bundle this track belongs to.
bundle_artists [Artist Object] Artists who produced this bundle.
bundle_mirror_artists [Artist Object] Artists who produced this bundle, with names
in reverse order.
label String Name of label who published this track.
track_title String Name of the track
track_mix_title String Name of the remix (only applies if track has
been remixed)
track_mix_artist String Name of the remix artist (only applies if track
has been remixed)
track_genre_id Int ID of the genre this track belongs to.
release_date Int Epoch timestamp when this track was
released.
track_length Int The length of the track as number of
seconds.

<track>
<formats>
[FORMAT OBJECT]
</formats>
<format_prices>
[FORMAT_PRICE OBJECT]
</format_prices>
<bundle_artists>
[ARTIST OBJECT]
</bundle_artists>
[ARTIST OBJECT]
</track>

33

10.2 Artist

artist String Artist name


10.3 Format

id Int Format identifier
Name String Format name
bit_rate String Bit rate of the format

<format>
<id>1</id>
<name>mp3</name>
</format>

10.4 Bundle

title_id Int Title ID
product_id Int Product ID
formats [Format Object] Formats that are available for this bundle.
Format_prices [Format Price Object] Available recommended prices
title String Name of album/single
artists [Artist Object] Artists who produced this bundle.
mirror_artists [Artist Object] Artists who produced this bundle, with names in
reverse order.
label String Name of label who published this product.
cat_no String Catalogue number for a product.
genre_id Int ID of the genre this product belongs to.
release_date Int Epoch timestamp when this track was released.
bundle_tracks [Bundle Track Object] The tracks which this bundle is comprised of.

<bundle>
<formats>
[FORMAT OBJECT]
</formats>
<format_prices>
</format_prices>
<artists>
[ARTIST OBJECT]
</artists>

34

<mirror_artists>
[ARTIST OBJECT]
</mirror_artists>
<bundle_tracks>
[BUNDLE TRACK OBJECT]
</bundle_tracks>
</bundle>

10.5 Bundle Track

track_id Int The position of this track in its bundle.
track_title String Name of the track
track_mix_title String Name of the remix (only applies if track has
been remixed)
track_mix_artist String Name of the remix artist (only applies if
track has been remixed)
track_genre_id Int ID of the genre this track belongs to.
track_length Int The length of the track as number of
seconds.
individual_sale Bit True means this track can be sold
individually, false means it can only be sold
as part of the bundle.
Format_prices [Format Price
Object]
Available recommended prices

<bundle_track>
<format_prices>
</format_prices>
</bundle_track>

10.6 Genre

id #### The genre ID always a 4 digit number.

name String Name of genre.

<genre>
<id>0001</id>
<name>Breakbeat</name>

35

</genre>

10.7 Country

id Int Country identifier

code String 2 letter country ISO code
name String Name of country

<country>
<id>1</id>
<code>AF</code>
<name>Afghanistan (Islamic St.)</name>
</country >

10.8 Currency

id Int Currency identifier

code String 3 letter currency ISO code
name String Name of Currency

<currency>
<id>1</id>
<code>GBP</code>
<name>Pound Sterling</name>
</currency>

10.9 Format_price

format_id int Format identifier
currency_code str 3 letter currency ISO code
amount float The value of the bundle/track
country_prices [COUNTRY_PRICE OBJECT] Specific price for countries using local
currency where applicable

<format_price>
<country_prices>
[COUNTRY_PRICE OBJECT]
</country_prices>
</format_price>

36

10.10 Country_price

Country_code Str Comma separated list of 2 letter country
ISO 3667 code
currency_code str 3 letter currency ISO code
amount float The value of the bundle/track

<country_price>
</country_price>

JunoAPI SEARCH v1.3.1

Uploaded by

Copyright:

Available Formats

JunoAPI SEARCH v1.3.1

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

JunoAPI SEARCH v1.3.1

Uploaded by

Copyright:

Available Formats

1

JUNO SEARCH API

You might also like