# Spotify Catalog Resolver: ISRC/UPC to 256M Tracks (`yungstentech/spotify-catalog-resolver`) Actor Resolve ISRCs, UPCs, ISWCs, or free-text queries to full Spotify catalog metadata (IDs, artists, album, cover, popularity, release date) over a pre-indexed 256M-track snapshot. No Spotify OAuth, no rate wall. - **URL**: https://apify.com/yungstentech/spotify-catalog-resolver.md - **Developed by:** [Paul Mikulskis](https://apify.com/yungstentech) (community) - **Categories:** Developer tools, Automation, Agents - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $15,000.00 / 1,000 catalog match reports This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use 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 Resolve **ISRCs, UPCs, ISWCs, or free-text queries** to full **Spotify catalog metadata** (Spotify IDs, artists, album, cover art, popularity, release date) in a single call, over a **pre-indexed 256M-track / 58M-album / 15M-artist snapshot**. No Spotify OAuth workflow, no Web API rate-wall dependency, and bulk all-variant resolution from an owned index. ### What does Spotify Catalog Resolver do? Spotify Catalog Resolver takes a list of **identifiers or search terms** and returns the matching Spotify catalog entities as structured rows. It runs against a purpose-built, pre-indexed Postgres full-text index of a Spotify metadata snapshot, so it answers **ISRC → track**, **UPC → album**, and **text → track/artist/album** lookups from a warm index in milliseconds, without putting each lookup through the Spotify Web API workflow. Because it runs on the Apify platform, you get API access, scheduling, integrations (Make, Zapier, n8n), monitoring, and downloadable datasets out of the box. ### Why use Spotify Catalog Resolver? - **Bulk ISRC and UPC resolution without the Spotify API workflow.** Spotify Search supports identifier filters, but it is OAuth-gated, rate-limited, and single-query oriented; this actor returns bulk and all-variant results from an owned 256M-track index. - **No OAuth workflow or Web API rate-wall dependency.** Resolve thousands of identifiers in one run. - **Bulk catalog matching.** Paste a list (or a CSV URL) of ISRCs/UPCs/titles and get every match back, plus an optional match report (how many resolved, how many didn't). - **Built for music-tech.** Rights and royalty tooling, catalog reconciliation, metadata enrichment, playlist/analytics pipelines, and AI music agents. ### How to use Spotify Catalog Resolver 1. Pick a **Query mode** (e.g. `Lookup by ISRC`, `Search tracks`, or `Bulk resolve`). 2. Add your values to **Queries**, one identifier or search phrase per item. For bulk jobs you can instead point **CSV URL** at a public CSV (the first column is used). 3. Set **Max rows per query** (1–50) to cap how many hits each value returns. 4. Click **Start**. Results stream into the dataset, one row per match. 5. Download the dataset as JSON, CSV, Excel, or HTML, or pull it from the API. ### Input Configure the run in the **Input** tab. | Field | Description | |---|---| | `mode` | `lookupIsrc`, `lookupUpc`, `lookupIswc`, `searchTracks`, `searchArtists`, `searchAlbums`, `typeahead`, or `bulk`. | | `queries` | Values to resolve: one ISRC/UPC/ISWC per item, or free text for search modes. | | `csvUrl` | Bulk mode only: a public CSV URL; the first column of each row is used as a query value. | | `limit` | Max hit rows returned per input value (1–50). | | `types` | Typeahead only: restrict to `track`, `artist`, and/or `album`. | | `includeReport` | Bulk only: add one summary row with matched / not-found counts. | Example input: ```json { "mode": "bulk", "queries": ["USUG12001402", "GBUM71029604", "00602507122591"], "limit": 1, "includeReport": true } ```` ### Output Each match is one dataset row. A track row looks like: ```json { "query": "USUG12001402", "mode": "lookupIsrc", "status": "matched", "type": "track", "spotifyId": "0VjIjW4GlUZAMYd2vXMi3b", "spotifyUrl": "https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b", "isrc": "USUG12001402", "name": "Blinding Lights", "albumName": "After Hours", "albumUpc": "00602508972164", "artistNames": ["The Weeknd"], "artistSpotifyIds": ["1Xyo4u8uXC1ZmMpatF05PJ"], "coverUrl": "https://i.scdn.co/image/ab67616d0000b273...", "coverWidth": 640, "coverHeight": 640, "durationMs": 200040, "popularity": 92, "releaseDate": "2020-03-20", "snapshotId": "2025-07" } ``` Values with no match produce a **free** status row (`status: "not_found"`, `"invalid"`, or `"warming"`) so every input is accounted for. You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. ### Demo dataset and catalog-match report The full multi-input demo is free to inspect, no run required. It was generated locally in bulk mode against the live snapshot from 3 identifiers: 2 real ISRCs and 1 synthetic probe not in the catalog. - **Dataset** (6 total rows: 5 result rows plus 1 catalog-match-report row): https://api.apify.com/v2/datasets/jTIj4w70lvyT0HyAg/items?format=json\&clean=true — `USUG12001402` (The Weeknd, "Blinding Lights - Major Lazer Remix") resolves to 2 release variants, `GBUM71029604` (Queen, "Bohemian Rhapsody") resolves to 2 release variants, and `ZZZZZ0000001` (a synthetic, non-existent ISRC) comes back `not_found`. - **Catalog-match report**: same dataset, the row with `"recordType": "catalog-match-report"` — the exact summary artifact a buyer gets from `includeReport: true`. Over these 3 identifiers: 2 matched, 1 not-found, 4 rows resolved. Generating your own report over your own list is the paid `catalog-match-report` event ($15, see Pricing); reading this sample one is free. The dataset and report above are real output from the shipped resolver (a local, non-billing bulk run), not mocked. An earlier single-run demo is still up at https://api.apify.com/v2/datasets/237XTcWzSgNldbitT/items?format=json\&clean=true: 4 matched rows, two release variants each for `USUG12001402` (The Weeknd) and `GBUM71029604` (Queen), and no report row. #### Related actors - [MLC Works Resolver](https://apify.com/yungstentech/mlc-works-resolver) resolves ISRCs to MLC songwriter/publisher rights and royalty shares. Use it for the rights layer; this actor is catalog metadata, not rights. #### Data fields | Field | Applies to | Description | |---|---|---| | `spotifyId` / `spotifyUrl` | all | Spotify entity ID and open.spotify.com link. | | `isrc` | track | International Standard Recording Code. | | `albumUpc` / `upc` | track / album | Universal Product Code (barcode). | | `name` | all | Track / artist / album name. | | `artistNames` / `artistSpotifyIds` | track / album | Credited artists and their Spotify IDs. | | `albumName` | track | Parent album. | | `coverUrl` / `coverWidth` / `coverHeight` | track / album | Cover art. | | `durationMs` / `popularity` / `releaseDate` | track | Track detail. | | `genres` / `followersTotal` / `portraitUrl` | artist | Artist detail. | | `albumType` / `label` / `totalTracks` | album | Album detail. | ### Pricing This actor is **pay-per-event**: - **`resolved-row`: $0.004** per matched row pushed to the dataset. - **`catalog-match-report`: $15** for the optional bulk summary report (only when `includeReport` is on). - **Actor start: $0.00001** per GB of run memory (a 4 GB run starts for $0.00004). Beyond that fraction-of-a-cent start event, you are only charged for **matches**. Not-found, invalid, and warming rows are always free, so a bulk job with misses never bills you for the misses. Resolving 1,000 ISRCs that all match at 1 row each costs about $4. ### Tips - For exact identifier resolution use the `lookup*` modes: they are index-backed, and a warm lookup returns in tens of milliseconds. - Use `limit: 1` in bulk mode when you only need the canonical match per identifier (keeps cost predictable). - Very common single words (e.g. a bare `"the"`) are expensive full-text queries and may return partial results; prefer specific titles or identifiers. ### FAQ, disclaimers, and support - **Where does the data come from?** A pre-indexed metadata snapshot (snapshot `2025-07`). It is a point-in-time index, not a live mirror of Spotify. - **Is this affiliated with Spotify?** No. Spotify is a trademark of Spotify AB; this actor is an independent metadata-resolution tool and is not endorsed by or affiliated with Spotify. - **Coverage.** Newer releases after the snapshot date may not be present; unmatched inputs return free status rows. - **Support / custom needs.** Use the Issues tab for feedback or to request a custom catalog-resolution solution. # Actor input Schema ## `mode` (type: `string`): What to resolve. `lookupIsrc`/`lookupUpc`/`lookupIswc` are exact-identifier lookups. `searchTracks`/`searchArtists`/`searchAlbums` are full-text searches. `typeahead` is a mixed-type search (auto-detects ISRCs). `bulk` auto-routes each value (ISRC -> UPC -> text) and can emit a summary report. ## `queries` (type: `array`): The values to resolve — one ISRC/UPC/ISWC per item for lookup modes, or free text for search modes. Each item produces one dataset row per hit (a charged `resolved-row`). Values with no match produce a FREE not-found status row. ## `csvUrl` (type: `string`): Bulk mode only. A public URL to a CSV; the first column of each row is used as a query value. Takes precedence over `queries` when set. ## `limit` (type: `integer`): Maximum hit rows returned (and charged) per input value. 1-50. ## `types` (type: `array`): Typeahead mode only. Restrict results to these entity types. Defaults to all three. ## `includeReport` (type: `boolean`): Bulk mode only. Emit one summary row (matched / not-found counts) as a `catalog-match-report` charge event. ## Actor input object example ```json { "mode": "lookupIsrc", "queries": [ "USUG12001402" ], "limit": 10, "includeReport": false } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "queries": [ "USUG12001402" ] }; // Run the Actor and wait for it to finish const run = await client.actor("yungstentech/spotify-catalog-resolver").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "queries": ["USUG12001402"] } # Run the Actor and wait for it to finish run = client.actor("yungstentech/spotify-catalog-resolver").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 '{ "queries": [ "USUG12001402" ] }' | apify call yungstentech/spotify-catalog-resolver --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=yungstentech/spotify-catalog-resolver", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Spotify Catalog Resolver: ISRC/UPC to 256M Tracks", "description": "Resolve ISRCs, UPCs, ISWCs, or free-text queries to full Spotify catalog metadata (IDs, artists, album, cover, popularity, release date) over a pre-indexed 256M-track snapshot. No Spotify OAuth, no rate wall.", "version": "0.0", "x-build-id": "xgotxB2lLuI2gauvA" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/yungstentech~spotify-catalog-resolver/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-yungstentech-spotify-catalog-resolver", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/yungstentech~spotify-catalog-resolver/runs": { "post": { "operationId": "runs-sync-yungstentech-spotify-catalog-resolver", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/yungstentech~spotify-catalog-resolver/run-sync": { "post": { "operationId": "run-sync-yungstentech-spotify-catalog-resolver", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Query mode", "enum": [ "lookupIsrc", "lookupUpc", "lookupIswc", "searchTracks", "searchArtists", "searchAlbums", "typeahead", "bulk" ], "type": "string", "description": "What to resolve. `lookupIsrc`/`lookupUpc`/`lookupIswc` are exact-identifier lookups. `searchTracks`/`searchArtists`/`searchAlbums` are full-text searches. `typeahead` is a mixed-type search (auto-detects ISRCs). `bulk` auto-routes each value (ISRC -> UPC -> text) and can emit a summary report.", "default": "lookupIsrc" }, "queries": { "title": "Queries", "type": "array", "description": "The values to resolve — one ISRC/UPC/ISWC per item for lookup modes, or free text for search modes. Each item produces one dataset row per hit (a charged `resolved-row`). Values with no match produce a FREE not-found status row.", "items": { "type": "string" } }, "csvUrl": { "title": "CSV URL (bulk mode)", "type": "string", "description": "Bulk mode only. A public URL to a CSV; the first column of each row is used as a query value. Takes precedence over `queries` when set." }, "limit": { "title": "Max rows per query", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum hit rows returned (and charged) per input value. 1-50.", "default": 10 }, "types": { "title": "Typeahead types", "type": "array", "description": "Typeahead mode only. Restrict results to these entity types. Defaults to all three.", "items": { "type": "string", "enum": [ "track", "artist", "album" ], "enumTitles": [ "Tracks", "Artists", "Albums" ] } }, "includeReport": { "title": "Include catalog-match report (bulk)", "type": "boolean", "description": "Bulk mode only. Emit one summary row (matched / not-found counts) as a `catalog-match-report` charge event.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```