{ "openapi": "3.0.1", "info": { "title": "Billboard Charts Scraper: Hot 100 & History", "description": "Scrape Billboard charts: Hot 100, Billboard 200, Global 200 and 12 more, for the current week or any week back to 1958. Get rank, title, artist, last week, peak, weeks on chart and cover art. Export CSV, Excel, JSON, XML. No login or API key. $10 per 1,000 entries.", "version": "0.1", "x-build-id": "QgEZ2ouIbxgKZhqQR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/recordsdata~billboard-charts-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-recordsdata-billboard-charts-scraper", "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/recordsdata~billboard-charts-scraper/runs": { "post": { "operationId": "runs-sync-recordsdata-billboard-charts-scraper", "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/recordsdata~billboard-charts-scraper/run-sync": { "post": { "operationId": "run-sync-recordsdata-billboard-charts-scraper", "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": [ "charts" ], "properties": { "charts": { "title": "Charts", "type": "array", "description": "Billboard charts to scrape: any chart slug from billboard.com/charts// (hot-100, billboard-200, billboard-global-200, artist-100, canadian-hot-100, official-uk-songs, japan-hot-100, streaming-songs, top-country-albums, ...; there are about 250) or a full chart URL, with or without a date. A slug that does not exist returns one error row and is not charged.", "items": { "type": "string" }, "default": [ "hot-100" ] }, "weeks": { "title": "Chart weeks (dates)", "type": "array", "description": "Chart dates as YYYY-MM-DD (Billboard weeks are Saturdays; nearby dates resolve to that week). Leave empty for the current week. Hot 100 history reaches back to 1958-08-04.", "default": [], "items": { "type": "string" } }, "startDate": { "title": "From date (YYYY-MM-DD)", "type": "string", "description": "First chart week to scrape. Billboard weeks are dated on Saturdays; any date is mapped to its week. Together with 'To date' the actor reads one chart page per week and per chart, up to 520 pages per run. Leave empty to use only the weeks above (or the latest chart).", "default": "" }, "endDate": { "title": "To date (YYYY-MM-DD)", "type": "string", "description": "Last chart week to scrape. Defaults to the latest chart when a From date is set.", "default": "" }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Maximum number of rows to return across all charts and weeks, including optional summary rows. Free users are limited to 10 items (preview). Paid users: optional, max 1,000,000. Leave empty for no limit." }, "positionsPerChart": { "title": "Positions per chart", "minimum": 1, "maximum": 200, "type": "integer", "description": "How many positions to keep from each chart week (e.g. 10 for a top-10).", "default": 100 }, "includeChartSummary": { "title": "Chart week summary row", "type": "boolean", "description": "One extra row per chart week: number 1 title/artist, biggest gainer and counts of new entries and re-entries. Billed as its own event.", "default": false }, "onlyNew": { "title": "Only new chart entries (monitor mode)", "type": "boolean", "description": "Only new entries: skip every chart entry this same search already returned in an earlier run, so a weekly scheduled run returns just the new chart week and you are not charged for skipped entries. Max Items then means N new entries. Off by default.", "default": false }, "stateKey": { "title": "Monitor name (optional)", "type": "string", "description": "Optional label for the monitor state. Use a different label to run several independent monitors with identical filters. Leave empty to share state between runs of the same search.", "default": "" }, "resetSeen": { "title": "Reset seen entries before this run", "type": "boolean", "description": "Clear the stored list of already-seen entries for this search (and Monitor name) before the run starts, so everything counts as new again.", "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }