# Shazam Charts Scraper (`automation-lab/shazam-charts-scraper`) Actor

Extract ranked tracks from Shazam global, country Top 200, and global Viral charts for music trend monitoring, A\&R research, and market analysis.

- **URL**: https://apify.com/automation-lab/shazam-charts-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Shazam Charts Scraper

Collect ranked tracks from Shazam's public global and country Top 200 charts and the global Viral chart.

Use structured chart snapshots for A\&R research, music-market monitoring, playlist planning, campaign measurement, and scheduled rank tracking—without a Shazam account or browser automation.

### What does Shazam Charts Scraper do?

Shazam Charts Scraper turns public Shazam chart pages into analysis-ready dataset rows.

It extracts:

- chart type and country scope;
- current chart rank;
- track title and credited artists;
- stable Shazam song ID;
- canonical Shazam song URL;
- available artwork URLs;
- source chart URL; and
- collection timestamp.

The Actor supports both friendly chart inputs and explicit Shazam chart URLs.

It uses server-rendered HTML rather than launching a browser, keeping runs quick and economical.

### Who is it for?

#### A\&R and label teams

Schedule country snapshots to spot tracks appearing in new markets.

#### Music marketers

Track chart positions before, during, and after a campaign.

#### Playlist and editorial teams

Build ranked candidate feeds from global and regional discovery signals.

#### Music-data analysts

Join stable song IDs and snapshot timestamps into longitudinal rank datasets.

#### Artist management teams

Monitor where a track is currently receiving strong Shazam discovery activity.

### Why use this Actor?

- **No account required:** the supported charts are publicly accessible.
- **Country comparison:** request several Shazam country slugs in one run.
- **Viral monitoring:** collect the global Viral chart as structured records.
- **Stable identifiers:** use `songId` instead of matching titles alone.
- **Integration-ready:** export JSON, CSV, Excel, XML, or RSS from Apify datasets.
- **Scheduler-friendly:** run the same scopes hourly or daily to measure movement.
- **Fail-closed parsing:** changed or blocked pages fail visibly instead of returning a misleading empty success.
- **Cloud-ready HTTP:** lightweight Apify datacenter proxy requests avoid browser automation.

This Actor captures chart snapshots. It does not estimate streams, sales, or audience size.

### Supported charts

| Chart | Scope | Typical size | Friendly input |
| --- | --- | ---: | --- |
| Top 200 | Global | Up to 200 tracks | `top-200` + `world` |
| Top 200 | Country | Up to 200 tracks | `top-200` + country slug |
| Viral | Global | Up to 50 tracks | `viral` + `world` |

Examples of country slugs include `finland`, `germany`, `united-kingdom`, and `united-states`.

Country availability follows Shazam's public chart pages.

Global Viral is the only Viral scope supported in this version.

### Extracted data

| Field | Type | Meaning |
| --- | --- | --- |
| `chartType` | string | `top-200` or `viral` |
| `country` | string | `world` or the Shazam country slug |
| `rank` | integer | Position in the requested chart |
| `trackTitle` | string | Track name displayed by Shazam |
| `artists` | string\[] | Credited artist names |
| `songId` | string | Stable numeric Shazam song identifier |
| `songUrl` | string | Canonical Shazam song page |
| `artworkUrl` | string/null | Largest advertised artwork URL |
| `artworkUrls` | string\[] | Available responsive artwork sizes |
| `sourceChartUrl` | string | Chart page that produced the row |
| `scrapedAt` | string | UTC ISO 8601 snapshot timestamp |

Artwork is linked, not downloaded.

Fields are nullable in the dataset schema because upstream markup can change.

### Getting started

1. Open **Shazam Charts Scraper** in Apify Console.
2. Keep **Chart type** set to `Top 200`.
3. Enter `world` under **Countries**.
4. Set **Maximum items** to `100` for a quick snapshot.
5. Keep the default Apify Proxy setting for reliable cloud access.
6. Click **Start**.
7. Open the **Results** dataset when the run succeeds.
8. Export the rows or connect the dataset to your workflow.

For a global Viral snapshot, select `Viral`, keep `world`, and set the limit to `50`.

### Input parameters

#### `chartType`

Friendly selector used when `startUrls` is empty.

Allowed values:

- `top-200` (default)
- `viral`

#### `countries`

A list of Shazam country slugs.

Default:

```json
["world"]
```

Use lowercase slugs from Shazam chart URLs.

For example:

```json
["finland", "germany", "united-kingdom"]
```

#### `startUrls`

Optional canonical Shazam chart URLs.

When this list is not empty, it overrides `chartType` and `countries`.

Accepted patterns are:

```text
https://www.shazam.com/charts/top-200/<country>
https://www.shazam.com/charts/viral/world
```

Other hosts, protocols, query strings, fragments, and unsupported chart paths fail validation.

#### `maxItems`

Maximum rows across all requested charts.

- Default: `100`
- Minimum: `1`
- Maximum: `1000`

The Actor stops before emitting more than the requested limit.

#### `proxyConfiguration`

Optional Apify Proxy settings.

Apify datacenter proxy use is enabled by default because Shazam rejects direct Apify cloud egress in current validation.

Disable proxy use only on a network where direct requests are verified; the direct route is cheaper but is not the reliable cloud default.

### Example inputs

#### Global Top 200

```json
{
  "chartType": "top-200",
  "countries": ["world"],
  "maxItems": 200,
  "proxyConfiguration": { "useApifyProxy": true }
}
```

#### Compare two countries

```json
{
  "chartType": "top-200",
  "countries": ["finland", "germany"],
  "maxItems": 400
}
```

#### Global Viral chart

```json
{
  "chartType": "viral",
  "countries": ["world"],
  "maxItems": 50
}
```

#### Explicit URL

```json
{
  "startUrls": [
    { "url": "https://www.shazam.com/charts/top-200/finland" }
  ],
  "maxItems": 25
}
```

### Output example

A current result has this shape:

```json
{
  "chartType": "viral",
  "country": "world",
  "rank": 1,
  "trackTitle": "Dynamite",
  "artists": ["BTS"],
  "songId": "1596532400",
  "songUrl": "https://www.shazam.com/song/1596532400/dynamite",
  "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music116/example/375x375bb.webp",
  "artworkUrls": [
    "https://is1-ssl.mzstatic.com/image/thumb/Music116/example/75x75bb.webp",
    "https://is1-ssl.mzstatic.com/image/thumb/Music116/example/375x375bb.webp"
  ],
  "sourceChartUrl": "https://www.shazam.com/charts/viral/world",
  "scrapedAt": "2026-07-25T04:56:50.258Z"
}
```

Ranks and chart contents change over time.

Use `songId` as the stable entity key and combine it with chart scope and `scrapedAt` for snapshots.

### Pricing

This Actor uses pay-per-event pricing.

- Actor start: **$0.005 per run**
- Chart track: tiered by Apify plan, from **$0.00036344 per item on Free** to **$0.000088491 on Diamond**
- The start fee remains unchanged and covers the measured fixed runtime and datacenter-proxy cost

| Apify plan | Price per chart track |
| --- | ---: |
| Free | $0.00036344 |
| Bronze | $0.00031604 |
| Silver | $0.00024651 |
| Gold | $0.00018962 |
| Platinum | $0.00012642 |
| Diamond | $0.000088491 |

Illustrative Bronze-plan costs:

| Workflow | Calculation | Estimated Actor charge |
| --- | --- | ---: |
| 10 tracks | $0.005 + 10 × $0.00031604 | $0.0082 |
| 50 Viral tracks | $0.005 + 50 × $0.00031604 | $0.0208 |
| 200 Top tracks | $0.005 + 200 × $0.00031604 | $0.0682 |
| Two full country charts | $0.005 + 400 × $0.00031604 | $0.1314 |

The Apify Console displays the active event prices for your plan before starting a run.

Proxy traffic, if enabled, may add platform usage charges under your Apify plan.

### Scheduling and rank movement

A single run is a snapshot.

To analyze movement:

1. Choose fixed chart scopes.
2. Schedule the Actor at a consistent interval.
3. Store or export each dataset.
4. Join records on `chartType`, `country`, and `songId`.
5. Compare `rank` across `scrapedAt` timestamps.

Do not use title-only matching because titles can collide or change formatting.

A daily schedule is suitable for broad monitoring.

A more frequent schedule may help campaign analysis but creates more snapshots and charges.

### Integration ideas

#### A\&R alerting

Send newly appearing song IDs to Slack, email, or a CRM.

#### Regional breakout detection

Compare country chart ranks and identify tracks that appear in one market before another.

#### Playlist research

Load daily snapshots into a spreadsheet or warehouse and rank sustained movers.

#### Campaign reporting

Join Shazam rank history with release dates and paid-media campaign windows.

#### Catalog enrichment

Use `songUrl`, title, and artists to resolve tracks against Spotify, MusicBrainz, or internal catalog IDs.

Apify integrations can connect datasets to Google Sheets, Zapier, Make, webhooks, and cloud storage.

### API usage

Replace `YOUR_TOKEN` with an Apify API token.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~shazam-charts-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chartType":"viral","countries":["world"],"maxItems":50}'
```

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/shazam-charts-scraper').call({
  chartType: 'top-200',
  countries: ['finland', 'germany'],
  maxItems: 100,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/shazam-charts-scraper').call(run_input={
    'chartType': 'top-200',
    'countries': ['world'],
    'maxItems': 100,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

Use the synchronous run endpoint only when the caller can wait for completion.

For larger workflows, start a run asynchronously and consume a webhook or poll its status.

### Use with Apify MCP

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/shazam-charts-scraper"
```

#### Claude Desktop, Cursor, and VS Code

Use this equivalent HTTP MCP configuration in Claude Desktop, Cursor, or VS Code:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/shazam-charts-scraper"
    }
  }
}
```

Example prompts:

- “Run the Shazam Charts Scraper for the global Viral chart and return the top 20 tracks.”
- “Collect the Finland and Germany Shazam Top 200 charts, then compare overlapping song IDs.”
- “Schedule a daily global Top 200 snapshot and summarize new entries.”

MCP authentication and tool permissions are managed by your Apify MCP setup.

### Limits and reliability

Shazam controls chart availability and page markup.

The Actor validates that each response contains recognizable chart records.

It retries transient network errors, HTTP 429 responses, and temporary server errors up to three times with backoff.

Deterministic invalid URLs and unsupported modes are not retried.

Chart pages are 1.5–3.7 MB, so charts are fetched sequentially to keep memory and network usage controlled.

The Actor does not download audio, video, or artwork files.

It does not scrape song detail pages because the chart page already contains the promised fields.

A naturally shorter chart can return fewer rows than `maxItems`.

### Troubleshooting

#### The Actor says the country chart is unsupported or empty

Open the corresponding public Shazam chart URL and copy its exact lowercase country slug.

Then use that slug in `countries` or provide the canonical URL in `startUrls`.

#### The Viral input fails

Use `countries: ["world"]` with `chartType: "viral"`.

Country Viral charts are not supported in this version.

#### Shazam returns a network or challenge error

Keep the default Apify datacenter proxy enabled and retry later. If you disabled proxy use, restore the default setting.

Do not enable residential traffic unless you have independently confirmed it is necessary and economical.

#### The run produced fewer items than expected

Check `maxItems`, requested chart scopes, and current source chart length.

The limit applies across all charts, not separately to each chart.

#### How do I inspect a failed run?

Open the run log in Apify Console.

Input errors name the invalid field or URL.

Response-shape errors indicate that Shazam returned an unexpected page rather than a valid empty chart.

### Responsible use and legality

This Actor accesses publicly available chart pages without authentication.

You are responsible for complying with Shazam's terms, applicable laws, and the rights attached to downstream use.

Collect only the data needed for a legitimate purpose.

Do not use the Actor to circumvent access controls.

Do not republish protected artwork or other media without appropriate rights.

Respect rate limits and choose a reasonable schedule.

Track and artist names may be copyrighted or trademarked in some contexts; attribution and downstream use remain your responsibility.

This documentation is operational guidance, not legal advice.

### FAQ

#### Does this Actor require a Shazam or Apple account?

No. The supported chart pages are public and the Actor does not use login credentials.

#### Does it return historical ranks?

No. Each run captures the current chart. Build history by scheduling repeated snapshots.

#### Does `rank` show movement since yesterday?

No. It is the current position. Compare scheduled datasets to calculate movement.

#### Can I scrape several countries in one run?

Yes. Add several country slugs and increase `maxItems` enough to include the desired rows.

#### Can I provide chart URLs directly?

Yes. Canonical `www.shazam.com/charts/...` URLs override the friendly chart inputs.

#### Are artwork files downloaded?

No. Dataset rows contain source URLs only.

#### Why is there no browser option?

The public chart records are server-rendered, so browser automation would add cost and memory without improving the supported output.

#### Can the Actor return more than 1,000 rows?

Not in one run. The v1 safety limit is 1,000 rows. Split large country sets across runs.

### Related Automation Lab Actors

- [Spotify Scraper](https://apify.com/automation-lab/spotify-scraper) for broader Spotify catalog and entity workflows.
- [Spotify Public Weekly Charts Scraper](https://apify.com/automation-lab/spotify-public-weekly-charts-scraper) for Spotify's global weekly chart signal.
- [MusicBrainz Scraper](https://apify.com/automation-lab/musicbrainz-scraper) for open music metadata enrichment.

Shazam chart rank is a song-discovery signal, while Spotify and MusicBrainz provide different catalog and chart contexts.

Use stable IDs from each source rather than assuming title text alone identifies the same recording.

# Actor input Schema

## `chartType` (type: `string`):

Friendly chart selector used when Start URLs are empty. Top 200 supports world and two-letter country codes; Viral currently supports world only.

## `countries` (type: `array`):

World or Shazam country slugs, for example world, finland, united-states, or germany. Ignored when Start URLs are supplied.

## `startUrls` (type: `array`):

Optional canonical Shazam chart URLs such as https://www.shazam.com/charts/top-200/finland. When provided, these override Chart type and Countries.

## `maxItems` (type: `integer`):

Maximum number of ranked tracks emitted across all requested charts.

## `proxyConfiguration` (type: `object`):

Apify Proxy settings. Datacenter proxy use is enabled by default because direct Apify cloud egress can be rejected by Shazam; disable it only on networks where direct requests are verified.

## Actor input object example

```json
{
  "chartType": "top-200",
  "countries": [
    "world"
  ],
  "startUrls": [],
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Ranked Shazam chart tracks.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "chartType": "top-200",
    "countries": [
        "world"
    ],
    "startUrls": [],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/shazam-charts-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "chartType": "top-200",
    "countries": ["world"],
    "startUrls": [],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/shazam-charts-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "chartType": "top-200",
  "countries": [
    "world"
  ],
  "startUrls": [],
  "maxItems": 20
}' |
apify call automation-lab/shazam-charts-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/shazam-charts-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/QN71jG80XI8FMht8C/builds/UbqYNsHbJp4ArYaaF/openapi.json