Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Use two independent request choices: set the catalog storefront to the country or region whose catalog you need, and set the optional l language tag to a language supported by that storefront. Omitting l uses the storefront’s default language. Then inspect the selected resource’s documented attributes before displaying a title, price, currency, or availability; Apple’s storefront documentation does not guarantee that every resource includes a price field.
Storefront and language solve different problems
An Apple Music API storefront is the regional catalog context. It controls which content and availability rules apply for a country or territory. The language parameter only changes how the response is localized; it does not switch the catalog to another country.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
$100 Apple Gift Card—Email Delivery | $100.00 | Buy on Amazon |
| 2 |
|
$15 Apple Gift Card—Email Delivery | $15.00 | Buy on Amazon |
| 3 |
|
$25 Apple Gift Card—Email Delivery | $25.00 | Buy on Amazon |
| 4 |
|
Apple Physical Gift Card | $100.00 | Buy on Amazon |
| Decision | API control | What it changes |
|---|---|---|
| Catalog country or region | Storefront path, such as /v1/catalog/us/... |
Regional catalog content and availability |
| Response language | Optional l query parameter |
Localized strings, when the storefront supports the requested language |
For example, /v1/catalog/us/albums/310730204 requests the US catalog. Adding ?l=es-MX asks Apple to localize the response in Mexican Spanish if that tag is supported by the US storefront. It does not request Mexico’s catalog.
Prices are resource-specific. A storefront establishes the regional context, but you must read the endpoint’s response schema to learn whether that resource exposes price, currency, and availability attributes.
#1 Best Overall
- For all things Apple - products, accessories, apps, games, music, movies, TV shows, iCloud+, and more.
- Perfect for App Store purchases and subscriptions—get apps, games, music, movies, TV shows, and more.
- The perfect gift to say happy birthday, thank you, congratulations, and more.
- Available in $15 - 500, Card delivered via email or SMS
- Use it for purchases at any Apple Store location, on the Apple Store app, apple.com, the App Store, iTunes, Apple Music, Apple TV, Apple News+, Apple Books, Apple Arcade, iCloud+, Fitness+, Apple One, and other Apple properties in US only
Prerequisites and authentication
- Create an Apple Music API developer token and send it with catalog requests in an
Authorization: Bearer ...header. Apple’s localization guidance lists the developer-token requirement. - Use HTTPS and keep the token on your server. Do not embed a developer token in browser JavaScript distributed to users.
- A signed-in listener’s storefront is a separate operation. Apple requires a Music User Token for
/v1/me/storefront; a developer token alone is not sufficient for that endpoint.
Validate a storefront before requesting localized data
Look up one storefront
GET /v1/storefronts/{id} accepts an ISO 3166 alpha-2 country code such as us, jp, or gb. The Storefront object reports the storefront name, its default language, and its supported language tags. Use this endpoint when a user has selected one country and you need to validate a language choice.
curl -H "Authorization: Bearer $APPLE_DEVELOPER_TOKEN"
"https://api.music.apple.com/v1/storefronts/jp"Apple’s example identifies Japan as jp, with ja as the default language and en-US also supported. Treat the returned list as authoritative rather than maintaining an assumed language matrix in your application.
List every storefront
GET /v1/storefronts is useful for a country picker, administrative cache, or validation service. It supports limit and offset, so continue requesting pages until the response contains no further entries or reaches the API’s documented end condition.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemscurl -H "Authorization: Bearer $APPLE_DEVELOPER_TOKEN"
"https://api.music.apple.com/v1/storefronts?limit=100&offset=0"Store the storefront identifier, name, default language, and supported language tags with a refresh policy. Do not assume that every storefront supports the same language tags.
Request a localized catalog resource
Use the default language
Omit l when the storefront’s default language is suitable:
curl -H "Authorization: Bearer $APPLE_DEVELOPER_TOKEN"
"https://api.music.apple.com/v1/catalog/us/albums/310730204"Override the language with a supported tag
Pass l only after checking the storefront’s supportedLanguageTags. Apple documents this pattern:
curl -G
-H "Authorization: Bearer $APPLE_DEVELOPER_TOKEN"
--data-urlencode "l=es-MX"
"https://api.music.apple.com/v1/catalog/us/albums/310730204"Use URL encoding for tags and other query values. If the requested language is not supported, remove the override and fall back to the storefront default, or present a language choice that your validation step has confirmed.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #2
- For all things Apple - products, accessories, apps, games, music, movies, TV shows, iCloud+, and more.
- Perfect for App Store purchases and subscriptions—get apps, games, music, movies, TV shows, and more.
- The perfect gift to say happy birthday, thank you, congratulations, and more.
- Available in $15 - 500, Card delivered via email or SMS
- Use it for purchases at any Apple Store location, on the Apple Store app, apple.com, the App Store, iTunes, Apple Music, Apple TV, Apple News+, Apple Books, Apple Arcade, iCloud+, Fitness+, Apple One, and other Apple properties in US only
Read titles, prices, and availability safely
Titles and other localized strings
Parse the resource’s documented attributes and treat localized text as display data. Keep the storefront and language used for each response alongside your cached object so that a US title in Spanish cannot be mistaken for a Spanish storefront result.
Prices and currency
Do not infer a price merely because a storefront was selected. The reviewed storefront documentation explains regional and language selection, not a universal price guarantee for every resource type. Before rendering a price:
- Open the documentation for the exact endpoint and resource type you call.
- Confirm the response contains a price attribute and identify its currency or formatted representation.
- Handle a missing, null, or unavailable value as “not available” rather than converting or guessing.
- Use the returned storefront context when labeling the result, and do not reuse a cached price from another storefront.
If your product needs a numeric amount for sorting or billing, verify that the resource supplies a stable numeric field and currency code. A display string alone is not a safe basis for arithmetic.
Determine the signed-in listener’s storefront
When the application must follow the current listener rather than a user-selected country, call GET /v1/me/storefront with both a developer token and the required Music User Token:
Free tools Windows power users keep installed
One-click scans. No signup required.
curl
-H "Authorization: Bearer $APPLE_DEVELOPER_TOKEN"
-H "Music-User-Token: $MUSIC_USER_TOKEN"
"https://api.music.apple.com/v1/me/storefront"Use the returned storefront identifier for subsequent catalog requests. This is different from allowing a user to browse another country’s storefront, which should use the explicitly selected storefront path.
Complete implementation examples
Python: validate, then fetch localized metadata
import os
import requests
BASE = "https://api.music.apple.com/v1"
TOKEN = os.environ["APPLE_DEVELOPER_TOKEN"]
headers = {"Authorization": f"Bearer {TOKEN}"}
storefront_id = "us"
storefront = requests.get(
f"{BASE}/storefronts/{storefront_id}",
headers=headers,
timeout=30,
)
storefront.raise_for_status()
storefront_data = storefront.json()["data"][0]["attributes"]
wanted_language = "es-MX"
supported = storefront_data.get("supportedLanguageTags", [])
params = {"l": wanted_language} if wanted_language in supported else {}
resource = requests.get(
f"{BASE}/catalog/{storefront_id}/albums/310730204",
headers=headers,
params=params,
timeout=30,
)
resource.raise_for_status()
result = resource.json()
print(result)The example falls back to the default language by omitting l when the requested tag is not listed. In production, extract only attributes documented for the specific resource and preserve the request storefront and language in your cache key.
Node.js: request a known storefront and language
const token = process.env.APPLE_DEVELOPER_TOKEN;
const storefront = 'us';
const params = new URLSearchParams({ l: 'es-MX' });
const url = `https://api.music.apple.com/v1/catalog/${storefront}/albums/310730204?${params}`;
const response = await fetch(url, {
headers: { Authorization: `Bearer ${token}` }
});
if (!response.ok) throw new Error(`Apple Music API: ${response.status}`);
const json = await response.json();
console.log(json);Pagination for a storefront directory
Request a bounded page, process its entries, increase offset by the number returned, and stop when the page is empty. Respect Apple’s documented limits and transient-error guidance rather than issuing an unbounded burst of requests.
Rank #3
- For all things Apple - products, accessories, apps, games, music, movies, TV shows, iCloud+, and more.
- Perfect for App Store purchases and subscriptions—get apps, games, music, movies, TV shows, and more.
- The perfect gift to say happy birthday, thank you, congratulations, and more.
- Available in $15 - 500, Card delivered via email or SMS
- Use it for purchases at any Apple Store location, on the Apple Store app, apple.com, the App Store, iTunes, Apple Music, Apple TV, Apple News+, Apple Books, Apple Arcade, iCloud+, Fitness+, Apple One, and other Apple properties in US only
Designing a reliable localization layer
Cache by all inputs that affect the result
A safe cache key includes the endpoint, resource identifier, storefront, language override (or “default”), and any other query parameters. Otherwise, a Spanish response can overwrite an English response or a US object can be served for another storefront.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Separate catalog choice from presentation choice
Let a user’s country selector control the storefront. Let a language selector control l, constrained by that storefront’s supported tags. If no language is selected, omit l and display the storefront default.
Plan for unavailable fields
Model title, price, currency, and availability as independently optional. A title may be localized while a price is absent for the resource. Render each field according to its presence instead of rejecting the whole object.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting
401 Unauthorized
Check that the developer token is present, unexpired, and sent as Authorization: Bearer TOKEN. For /v1/me/storefront, also send a valid Music User Token.
404 Not Found
Verify the storefront code, resource type, and identifier. A resource that exists in one storefront may not exist in another.
Language is ignored
Confirm that l exactly matches a tag returned by the storefront’s supportedLanguageTags. If it is unsupported, omit it and use the documented default.
Expected price is missing
Check the exact resource schema. Storefront selection does not establish that every Apple Music API object exposes a price. Treat an absent value as unavailable.
Rank #4
- For all things Apple - products, accessories, apps, games, music, movies, TV shows, iCloud+, and more.
- Perfect for App Store purchases and subscriptions—get apps, games, music, movies, TV shows, and more.
- The perfect gift to say happy birthday, thank you, congratulations, and more.
- Available in $100 and $200, Card delivered via mail.
- Use it for purchases at any Apple Store location, on the Apple Store app, apple.com, the App Store, iTunes, Apple Music, Apple TV, Apple News+, Apple Books, Apple Arcade, iCloud+, Fitness+, Apple One, and other Apple properties in US only
Wrong country appears in the result
Inspect the URL path, not only the language query. The storefront is the segment after /catalog/; changing l cannot change that region.
Or skip the browser setup
If you also need clean screenshots of localized pages for QA or documentation, ScreenshotNeo provides a one-call website screenshot API and MCP server. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →With an API key, call the endpoint directly (see the ScreenshotNeo API documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo also offers an MCP server so Claude, Cursor, and other MCP clients can use take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Frequently Asked Questions
Can I use a language tag to retrieve another country’s catalog?
No. The catalog storefront in the URL selects the country or region. The l parameter only requests a supported response language for that storefront.
How should I populate a country and language picker?
Fetch storefronts, read each object’s default and supported language tags, and allow only those tags for that storefront. Use limit and offset while paging through /v1/storefronts.
Which token identifies a listener’s region?
The /v1/me/storefront endpoint requires a Music User Token in addition to the developer token.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
