Enterprise Partner Feed Flat
The Enterprise Partner Feed is a data feed of the complete set of metadata from iTunes and the App Store. It is available for affiliate partners to fully incorporate aspects of the iTunes and App Store catalogs into a web site or app. The EPF is available in two different formats - either as the files necessary to build a relational database or as stand-alone flat files that are country and media dependent. EPF Relational consists of four files that when expanded can be ingested to build a relational database. This format is directed towards tech-savvy affiliate partners who can ingest, build and maintain a database and need information for either multiple media types or for multiple storefronts. The EPF Flat data feeds are separate files for music, movies or apps as well as for each storefront. These feeds are directed towards slightly less technical partners who only need a subset of the metadata for a specific media type for a specific country. The EPF-Flat files can be used as a stand alone documents and do not require ingestion into a database to be used. Access to both formats requires login credentials and an active partnership with the affiliate program. Partners wishing to apply for access can do so by emailing EPFrequest@apple.com with the primary account holders contact info, proof of being active with the affiliate program and a short description explaining how they intend to use the EPF. |
Table of Contents
Document Revision History
The following table describes the changes to this document.Date | Version | Notes |
|---|---|---|
2010/07/08 |
1.0 |
Initial revision |
Overview
Enterprise Partner Feed Flat (EPF-Flat) is a bulk data feed that contains a flattened subset of content metadata in the iTunes Store. It is intended to be a simplified subset of the more complex EPF Relational data feed. Partners who need a more complete data feed or who plan on importing iTunes data into a relational database may want to consider using EPF Relational as an alternative to EPF Flat.The data is made available as a set of compressed archive files that can be unarchived as plain text files, each of which contains a set of fields for a particular content type. These files are organized into directories based on country and date and are made available for download over HTTP. EPF Flat data files differ from EPF Relational in the following important ways:
- Each EPF Flat file is a self-contained set of data, with no primary and foreign key relationships to data in other files.
- EPF Flat contains only a subset of the fields available in the full EPF Relational data feed.
- EPF Flat files are tab-delimited text files that can be opened by a wide range of applications, including most spreadsheets (for example, Microsoft Excel) and text editors.
- Partners using EPF Flat data for affiliate link generation should refer to the EPF Relational documentation for instructions on creating links using the data provided.
File Format
As stated above, EPF Flat files are plain text files, which consist of linefeed-separated lines. At the top of each file are a few lines of comments, preceded by the "#" character, which describe the contents of the file. Subsequent lines consist of a set of tab-delimited fields, each of which represents one record for the content type specific to that file.Comment Records
Any line starting with a "#" should be treated as a comment and should not be imported. Important file metadata is included in the comments at the beginning of each file, including:
- A list of column names for the file
- A suggested primary key for the database table (preceded by "primaryKey:")
- Suggested database types and widths for each column (preceded by "dbTypes:")
Downloading the Feed
EPF Flat files are generated daily and made available for download using a username and password that Apple issues to its partners at: http://feeds.itunes.apple.com/feeds/epf-flat/v1/full/.
The files are divided into separate directories for each of the countries for which EPF Flat data is available. Each directory is named after a lowercase ISO3A country code. The list of countries and their ISO3A country codes are listed below. For example, files for the United States are in http://feeds.itunes.apple.com/feeds/epf-flat/v1/full/usa.
Inside each country-specific directory is another set of folders that contains EPF Flat files named by date in the format YYYYMMDD, where YYYY is year, MM is month, and DD is day. For example, http://feeds.itunes.apple.com/feeds/epf-flat/v1/full/usa/20100709/ contains files for July 9, 2010.
However, you can always get to the most recent files for a particular country by opening the directory named current. For example, the most recent files for the United States are always found in http://feeds.itunes.apple.com/feeds/epf-flat/v1/full/usa/current/.
Inside the last level of directories are compressed archives for each of the content types supported by EPF Flat and md5 files that can be used to verify the checksums for those files. The files are named by content type, country, and date that they were created. For example, if you open the link above to the files for July 9, 2010 in the United States, you will see the following files, for software applications, songs, and TV episodes, respectively:
application-usa-20100709.tbz
application-usa-20100709.tbz.md5
song-usa-20100709.tbz
song-usa-20100709.tbz.md5
tvEpisode-usa-20100709.tbz
tvEpisode-usa-20100709.tbz.md5
These files are archived using the UNIX tar command and compressed using bzip2. They can be unpacked on any UNIX host or on Windows with Cygwin installed, by cd'ing to the directory they are downloaded to from a command line and entering the command tar -jxvf <filename>.tbz. Unarchiving utilities with more user-friendly graphical interfaces that are able to unpack these files are also available for all major desktop platforms.
Detailed File Definition
This section describes the columns that are available for each of the content types supported by EPF Flat, which are currently Applications, Songs, and TV Episodes. The fields available for each content type are as follows:
application
| Name | Database Type | Description |
|---|---|---|
| title | VARCHAR(1000) | The title of the app, defaulting to the app's native language if a translation is not available. |
| developer_name | VARCHAR(1000) | The name of the application developer or company. |
| seller_name | VARCHAR(1000) | The legal entity name of the software provider. |
| primary_genre_name | VARCHAR(200) | The primary genre's name, such as "Rock" or "Pop." |
| application_url | VARCHAR(1000) | The URL to view this app in the App Store. |
| company_url | VARCHAR(1000) | The URL for this application on the seller's website. |
| support_url | VARCHAR(1000) | The URL to visit for application support. |
| icon_url_large | VARCHAR(1000) | The URL for the app's large icon. |
| icon_url_small | VARCHAR(1000) | The URL for the app's small icon. |
| first_screenshot_url | VARCHAR(1000) | The URL for the app's first screenshot. |
| content_rating | VARCHAR(200) | The minimum suggested age for a child to use this application. |
| version | VARCHAR(100) | The version number provided by the application developer. |
| itunes_version | VARCHAR(100) | The version string as set by iTunes. |
| supported_devices | VARCHAR(400) | Devices the application is supported on. |
| price | DECIMAL(9,3) | The price of the app, formatted for the given country. |
| itunes_release_date | DATETIME | The release date of the application on the App Store. |
| copyright | VARCHAR(4000) | The application's copyright. |
| download_size | BIGINT | The application's file size, in bytes. |
song
| Name | Database Type | Description |
|---|---|---|
| song_name | VARCHAR(1000) | The song's name. |
| album_name | VARCHAR(1000) | The album's name. |
| artist_name | VARCHAR(1000) | The artist's name. |
| composer_name | VARCHAR(1000) | The composer's name. |
| primary_genre_name | VARCHAR(200) | The primary genre's name, such as "Rock" or "Pop." |
| isrc | VARCHAR(200) | The International Standard Recording Code for the song. |
| upc | VARCHAR(200) | The Universal Product Code for the album. |
| song_url | VARCHAR(1000) | The URL to view the song on the iTunes Store. |
| artist_url | VARCHAR(1000) | The URL to view the artist's page on the iTunes Store. |
| composer_url | VARCHAR(1000) | The URL to view the composer's page on the iTunes Store. |
| album_artwork_url | VARCHAR(1000) | The URL for a 100 x 100 image of the album. |
| song_preview_url | VARCHAR(1000) | The URL for a 30-second preview of the song. |
| song_price | DECIMAL(9,3) | The price of the song, formatted for the given country. |
| album_price | DECIMAL(9,3) | The price of the album, formatted for the given country. |
| p_line | VARCHAR(4000) | The Track Label for the song. |
| copyright | VARCHAR(4000) | Copyright information for the song. |
| track_length | BIGINT | The length of the track, in milliseconds. |
| original_release_date | DATETIME | The date at which the album was first released. |
| itunes_release_date | DATETIME | The date at which the album first appeared on the iTunes Store. |
| content_rating | VARCHAR(200) | Indicates if the song has explicit lyrics. |
tvEpisode
| Name | Database Type | Description |
|---|---|---|
| title | VARCHAR(1000) | The title of the TV episode. |
| network | VARCHAR(1000) | The network of the TV episode. |
| production_number | VARCHAR(200) | The episode production number. |
| season | VARCHAR(1000) | TV season. |
| original_release_date | DATETIME | The date at which the TV episode was first aired. |
| copyright | VARCHAR(4000) | The copyright of the TV episode. |
| episode_url | VARCHAR(1000) | The URL to view the TV episode on the iTunes Store. |
| episode_artwork_url | VARCHAR(1000) | The URL for the episode's artwork as a 133 x 100 image. |
| upc | VARCHAR(200) | The Universal Product Code. |
| isan | VARCHAR(200) | The International Standard Audiovisual Number. |
| formats | VARCHAR(200) | The formats in which the TV episode is available. |
| sd_price | DECIMAL(9,3) | The price to buy the TV episode in Standard Quality format. |
| hq_price | DECIMAL(9,3) | The price to buy the TV episode in High Quality format. |
| lc_rental_price | DECIMAL(9,3) | The price to rent the TV episode in Low Quality format. |
| sd_rental_price | DECIMAL(9,3) | The price to rent the TV episode in Standard Quality format. |
| hd_rental_price | DECIMAL(9,3) | The price to rent the TV episode in High Quality format. |
Reference
ISO3A Country Codes
| Country | ISO3A Country Code |
|---|---|
| Australia | aus |
| Austria | aut |
| Belgium | bel |
| Canada | can |
| Denmark | dnk |
| Finland | fin |
| France | fra |
| Germany | deu |
| Greece | grc |
| Ireland | irl |
| Italy | ita |
| Japan | jpn |
| Luxembourg | lux |
| Mexico | mex |
| Netherlands | nld |
| New Zealand | nzl |
| Norway | nor |
| Portugal | prt |
| Spain | esp |
| Sweden | swe |
| Switzerland | che |
| United Kingdom | gbr |
| United States | usa |
© 2010 Apple Inc. All rights reserved. Apple, the Apple logo, iPod, iTunes, and WebObjects are trademarks of Apple Inc., registered in the United States and other countries. App Store is a service mark of Apple Inc. iTunes Store is a registered service mark of Apple Inc. iPhone is a trademark of Apple Inc. This document is Apple confidential.
Java and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
UNIX is a registered trademark of The Open Group.
