You have a short audio clip or a direct link to a song preview and you need to identify the track quickly so you can ship your music feature this week. By the end of this guide you’ll be able to recognize a song by URL (or by raw audio) using the Shazam API on Zyla API Hub, parse the fields you need (artist, title, Apple Music links, cover art), and integrate it into your service with a minimal, production-ready workflow.
What this API does and when to use it
The Shazam API on Zyla API Hub recognizes music from short audio samples and returns structured metadata about the track. Typical applications include:
- Identifying background music in user uploads or live recordings.
- Matching track previews from links to canonical metadata for display or catalog linking.
- Powering music discovery features (e.g., “What’s playing?” buttons in apps).
Two endpoints are available for recognition:
- Recognize Song (POST): send a short audio sample and receive the recognized track and metadata.
- Recognize Song By URL (GET): provide a direct URL to media (mp3, wav, ogg, mp4, wav or avi) and receive recognition results.
The API expects around 3–5 seconds of audio, no more than 3 MB (optimally ~500 KB). A practical approach is to send chunks until you get a match.
Getting started on Zyla API Hub
Open the Shazam API listing on Zyla API Hub, click Subscribe or start the available trial, and copy your API key. Authentication is via Authorization: Bearer YOUR_API_KEY. Billing is subscription + quota (not pay-per-call). For first integrations, you can use the 7-day trial available on the listing. Check the API page for current access options and pricing.
Start 7-day trial on Shazam API
Endpoints you will use
1) Recognize Song (POST)
Identify a track by sending a short audio sample file (3–5 seconds, ≤ 3 MB; 500 KB is optimal). The API returns a match set and a detailed track object when a match is found.
- Method: POST
- URL: https://zylalabs.com/api/2219/shazam-api/2068/recognize-song
- Headers: Authorization: Bearer YOUR_API_KEY
- Request parameters: not documented (send audio according to your client’s capabilities; best practice is chunking until a match is found)
Official cURL example:
curl -s -X POST "https://zylalabs.com/api/2219/shazam-api/2068/recognize-song" \
-H "Authorization: Bearer YOUR_API_KEY"
Official example response:
{"location":{"accuracy":0.01},"matches":[{"frequencyskew":0.0003222227,"id":"299052394","offset":48.000933593,"timeskew":0.0003027916}],"tagid":"75274D5F-ECCE-4104-B963-86CDC8059A13","timestamp":2453123822,"timezone":"Europe/Moscow","track":{"albumadamid":"495924692","alias":"freak-the-freak-out","artists":[{"adamid":"367602854","alias":"victorious-cast","id":"42"},{"adamid":"422753971","alias":"victoria-justice","id":"42"}],"genres":{"primary":"Soundtrack"},"highlightsurls":{},"hub":{"actions":[{"id":"495924694","name":"apple","type":"applemusicplay"},{"name":"apple","type":"uri","uri":"https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview115/v4/44/9b/fb/449bfb1f-8f65-fc6a-61e7-61e9b3e7cfba/mzaf_75952485968949724.plus.aac.ep.m4a"}],"displayname":"APPLE MUSIC","explicit":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/applemusic.png","options":[{"actions":[{"name":"hub:applemusic:deeplink","type":"applemusicopen","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"},{"name":"hub:applemusic:deeplink","type":"uri","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"}],"beacondata":{"providername":"applemusic","type":"open"},"caption":"OPEN IN","colouroverflowimage":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/overflow-open-option.png","listcaption":"Open in Apple Music","overflowimage":"https://images.shazam.com/static/icons/hub/web/v5/applemusic-overflow.png","providername":"applemusic","type":"open"}],"type":"APPLEMUSIC"},"images":{"background":"https://is1-ssl.mzstatic.com/image/thumb/Features115/v4/09/9d/29/099d2956-660c-f175-2ae7-172272fdf971/mzl.whswoyuz.jpg/800x800cc.jpg","coverart":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","coverarthq":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","joecolor":"b:151235p:e0abacs:e39577t:b78c94q:ba7b6a"},"isrc":"USSM11004546","key":"52910892","layout":"5","relatedtracksurl":"https://cdn.shazam.com/shazam/v3/en-US/GB/web/-/tracks/track-similarities-id-52910892?startFrom=0&pageSize=20&connected=","releasedate":"1…
What to look for in the response:
matches: array with timing/skew data for the match; can be used to verify confidence heuristically alongside other fields.tagid,timestamp,timezone: recognition context and timing (timezone is a string like Europe/Moscow).track: the core metadata block:alias: slug-like track alias.artists: array of contributors; useful for display and catalog cross-referencing.genres.primary: primary genre label.hub: actions and deep links (e.g., Apple Music play and open URIs).images: artwork and background images for UX.isrc: international sound recording code for catalog matching.key: Shazam track key identifier.
2) Recognize Song By URL (GET)
Identify a track by providing a direct URL to an audio/video file. Supported formats include mp3, wav, ogg, mp4, wav or avi. Use a short clip: 3–5 seconds (≤ 3 MB, ~500 KB is optimal). Chunking is recommended until a match is found.
- Method: GET
- URL: https://zylalabs.com/api/2219/shazam-api/7767/recognize-song-by-url
- Headers: Authorization: Bearer YOUR_API_KEY
- Query parameters:
url(string, required): direct media URL, e.g.,https://p.scdn.co/mp3-preview/d4d9aa2c6b44dda05115e4e983e741caf4efde40
The API returns a match array and track metadata similar to the POST endpoint when a match is found.
Copy-paste code you can ship
Python example: Recognize a song by URL
This example calls the Recognize Song By URL endpoint and extracts a few useful fields for your product UI. Replace YOUR_API_KEY with your Zyla API key.
import os
import urllib.parse
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
base = "https://zylalabs.com/api/2219/shazam-api/7767/recognize-song-by-url"
media_url = "https://p.scdn.co/mp3-preview/d4d9aa2c6b44dda05115e4e983e741caf4efde40"
params = {"url": media_url}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(base, headers=headers, params=params, timeout=30)
resp.raise_for_status()
data = resp.json()
# Minimal parsing with guard rails
track = data.get("track", {})
title_alias = track.get("alias")
artists = [a.get("alias") for a in track.get("artists", []) if isinstance(a, dict)]
isrc = track.get("isrc")
images = track.get("images", {})
cover_art = images.get("coverart") or images.get("coverarthq")
hub = track.get("hub", {})
actions = hub.get("actions", []) if isinstance(hub, dict) else []
apple_preview = None
apple_open_uri = None
for a in actions:
if a.get("type") == "applemusicplay" and "id" in a:
# ID present; preview may be available via another 'uri' action
continue
if a.get("type") == "uri" and a.get("name") == "apple":
apple_preview = a.get("uri")
break
# Fallback into hub.options for deeplinks if present
options = hub.get("options", []) if isinstance(hub, dict) else []
for opt in options:
for act in opt.get("actions", []):
if act.get("type") in ("applemusicopen", "uri"):
apple_open_uri = act.get("uri")
break
if apple_open_uri:
break
print("Matched alias:", title_alias)
print("Artists:", ", ".join([a for a in artists if a]))
print("ISRC:", isrc)
print("Cover art:", cover_art)
print("Apple preview:", apple_preview)
print("Apple Music deeplink:", apple_open_uri)
Notes that save time:
- Send short media: 3–5 seconds. Avoid full tracks; large files slow recognition and may exceed the size expectation.
- The API returns timezone as a string (e.g., Europe/Moscow) and a numeric
timestamp. If you cache results, store both the request URL and a hash of the media bytes for idempotency. hub.actionsandhub.optionscan contain Apple Music previews and deep links; check both to populate your playback and “Open in” CTAs.- For UI image rendering, prefer
coverarthqwhen present; fall back tocoverartorimages.background.
Production checklist for recognizing by URL
- Normalize media durations to ~3–5 seconds before calling the API.
- Ensure the URL is directly fetchable (no redirects that require cookies or auth).
- Cache positive matches by
isrcand Shazamkey; cache negatives for a short TTL to avoid repeated misses. - Log
tagidwith your request ID to correlate recognition attempts server-side. - Respect your plan’s quota (subscription + quota, not pay-per-call). For initial development, use the 7-day trial on the listing; if you need more volume, check the API page for current access options and pricing.
How to wire this into your app today
Backend flow for URL-based recognition
- Receive a client-submitted media URL (e.g., a short mp3 preview).
- Validate the URL and that it points to a supported format (mp3, wav, ogg, mp4, wav or avi).
- Call Recognize Song By URL with the encoded URL and your Authorization header.
- On success, map
track.alias,track.artists,track.isrc, artwork fromtrack.images, and playable/deeplink URIs fromtrack.hub. - If no match, retry with a different 3–5 second segment (chunking) or return a graceful “no match” state.
Backend flow for raw audio samples
- Record or accept a short 3–5 second clip client-side and transmit it to your backend.
- Call Recognize Song (POST). Best practice: send chunks until a match is found.
- Extract the same fields as the URL flow and persist results for future reuse.
Call the API from AI agents via MCP
If you automate tasks using MCP-compatible tools, you can make the same recognition calls through the Zyla MCP endpoint. Point your agent to:
Use your Zyla API key as usual (Authorization: Bearer YOUR_API_KEY). From there, instruct your MCP client (e.g., within a code-oriented assistant) to issue a GET to the Recognize Song By URL endpoint with the url parameter, or a POST to Recognize Song for raw audio. This is useful for rapid prototyping or when you want an agent to chain: “fetch short preview → recognize → post-process metadata → update a database.”
Error handling, reliability, and field usage tips
- Retries: For transient network failures, a single retry with jitter is usually enough. Avoid hot loops to stay within quota.
- Partial matches: Inspect the
matchesarray presence and non-emptiness alongside the availability of atrackobject before updating your UI. - Regional data: The response includes a
timezonelabel; do not assume it matches the user’s locale—treat it as context for when/where the recognition occurred. - Playable links: The Apple Music preview and deep links live under
hub.actionsandhub.options. Confirm type and name before surfacing a button.
Testing and validation ideas
- Use a handful of known preview URLs (short mp3s) and verify that
isrc, artist aliases, and cover art load as expected in your UI. - Test different 3–5 second slices of the same track to confirm your chunking logic gracefully retries when a match is not found on the first attempt.
- Record clips at varying volumes and with mild background noise to ensure your pre-processing keeps files within the size guideline and duration.
Frequently asked questions
How short can the audio be?
Around 3–5 seconds is recommended. Files should be no more than 3 MB, with ~500 KB considered optimal.
Which formats are supported for URL-based recognition?
The Recognize Song By URL endpoint supports mp3, wav, ogg, mp4, wav or avi, provided via a direct, fetchable URL.
What fields should I store for future lookups?
Store track.isrc, track.key, artist aliases, and any artwork URLs you actually render, plus playable/deeplink URIs you surface in your UI. Include tagid and timestamp if you need auditability.
Is there a free plan?
No Free Plan. The API uses subscription + quota (not pay-per-call). For first-time use, you can access a 7-day trial on the listing. Check the API page for current access options and pricing.
Can I call this from an AI coding assistant?
Yes. Use the Zyla MCP endpoint to let your agent make the same GET/POST calls with your Authorization header.
Ship it
You now have the exact endpoints and a working pattern to recognize songs by URL or raw audio, map track metadata, and surface artwork and Apple Music links in your product. Start with short 3–5 second clips, parse the track block, and wire in chunked retries for reliability. When you’re ready, get your key and start testing with the 7-day trial on the listing: Start 7-day trial on Shazam API.
Official API response
{"location":{"accuracy":0.01},"matches":[{"frequencyskew":0.0003222227,"id":"299052394","offset":48.000933593,"timeskew":0.0003027916}],"tagid":"75274D5F-ECCE-4104-B963-86CDC8059A13","timestamp":2453123822,"timezone":"Europe/Moscow","track":{"albumadamid":"495924692","alias":"freak-the-freak-out","artists":[{"adamid":"367602854","alias":"victorious-cast","id":"42"},{"adamid":"422753971","alias":"victoria-justice","id":"42"}],"genres":{"primary":"Soundtrack"},"highlightsurls":{},"hub":{"actions":[{"id":"495924694","name":"apple","type":"applemusicplay"},{"name":"apple","type":"uri","uri":"https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview115/v4/44/9b/fb/449bfb1f-8f65-fc6a-61e7-61e9b3e7cfba/mzaf_75952485968949724.plus.aac.ep.m4a"}],"displayname":"APPLE MUSIC","explicit":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/applemusic.png","options":[{"actions":[{"name":"hub:applemusic:deeplink","type":"applemusicopen","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"},{"name":"hub:applemusic:deeplink","type":"uri","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"}],"beacondata":{"providername":"applemusic","type":"open"},"caption":"OPEN IN","colouroverflowimage":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/overflow-open-option.png","listcaption":"Open in Apple Music","overflowimage":"https://images.shazam.com/static/icons/hub/web/v5/applemusic-overflow.png","providername":"applemusic","type":"open"}],"type":"APPLEMUSIC"},"images":{"background":"https://is1-ssl.mzstatic.com/image/thumb/Features115/v4/09/9d/29/099d2956-660c-f175-2ae7-172272fdf971/mzl.whswoyuz.jpg/800x800cc.jpg","coverart":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","coverarthq":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","joecolor":"b:151235p:e0abacs:e39577t:b78c94q:ba7b6a"},"isrc":"USSM11004546","key":"52910892","layout":"5","relatedtracksurl":"https://cdn.shazam.com/shazam/v3/en-US/GB/web/-/tracks/track-similarities-id-52910892?startFrom=0&pageSize=20&connected=","releasedate":"1…
Official API response
{"location":{"accuracy":0.01},"matches":[{"frequencyskew":0.0003222227,"id":"299052394","offset":48.000933593,"timeskew":0.0003027916}],"tagid":"75274D5F-ECCE-4104-B963-86CDC8059A13","timestamp":2453123822,"timezone":"Europe/Moscow","track":{"albumadamid":"495924692","alias":"freak-the-freak-out","artists":[{"adamid":"367602854","alias":"victorious-cast","id":"42"},{"adamid":"422753971","alias":"victoria-justice","id":"42"}],"genres":{"primary":"Soundtrack"},"highlightsurls":{},"hub":{"actions":[{"id":"495924694","name":"apple","type":"applemusicplay"},{"name":"apple","type":"uri","uri":"https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview115/v4/44/9b/fb/449bfb1f-8f65-fc6a-61e7-61e9b3e7cfba/mzaf_75952485968949724.plus.aac.ep.m4a"}],"displayname":"APPLE MUSIC","explicit":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/applemusic.png","options":[{"actions":[{"name":"hub:applemusic:deeplink","type":"applemusicopen","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"},{"name":"hub:applemusic:deeplink","type":"uri","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"}],"beacondata":{"providername":"applemusic","type":"open"},"caption":"OPEN IN","colouroverflowimage":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/overflow-open-option.png","listcaption":"Open in Apple Music","overflowimage":"https://images.shazam.com/static/icons/hub/web/v5/applemusic-overflow.png","providername":"applemusic","type":"open"}],"type":"APPLEMUSIC"},"images":{"background":"https://is1-ssl.mzstatic.com/image/thumb/Features115/v4/09/9d/29/099d2956-660c-f175-2ae7-172272fdf971/mzl.whswoyuz.jpg/800x800cc.jpg","coverart":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","coverarthq":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","joecolor":"b:151235p:e0abacs:e39577t:b78c94q:ba7b6a"},"isrc":"USSM11004546","key":"52910892","layout":"5","relatedtracksurl":"https://cdn.shazam.com/shazam/v3/en-US/GB/web/-/tracks/track-similarities-id-52910892?startFrom=0&pageSize=20&connected=","releasedate":"1…