{"id":20455651,"url":"https://github.com/datamgmt/music-chart-downloader","last_synced_at":"2026-05-13T23:32:59.409Z","repository":{"id":239025983,"uuid":"794941992","full_name":"datamgmt/Music-Chart-Downloader","owner":"datamgmt","description":"Download Music Chart Data ","archived":false,"fork":false,"pushed_at":"2025-04-26T12:51:39.000Z","size":394904,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-20T12:49:41.267Z","etag":null,"topics":["beautifulsoup","csv","json","music","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datamgmt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-02T09:14:04.000Z","updated_at":"2025-04-26T12:51:42.000Z","dependencies_parsed_at":"2025-01-15T23:05:21.202Z","dependency_job_id":"ceff5dd3-a4db-40a0-9cb3-f9e79666914b","html_url":"https://github.com/datamgmt/Music-Chart-Downloader","commit_stats":null,"previous_names":["datamgmt/music-chart-downloader"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/datamgmt/Music-Chart-Downloader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datamgmt%2FMusic-Chart-Downloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datamgmt%2FMusic-Chart-Downloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datamgmt%2FMusic-Chart-Downloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datamgmt%2FMusic-Chart-Downloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datamgmt","download_url":"https://codeload.github.com/datamgmt/Music-Chart-Downloader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datamgmt%2FMusic-Chart-Downloader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280094905,"owners_count":26271003,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-20T02:00:06.978Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beautifulsoup","csv","json","music","python"],"created_at":"2024-11-15T11:19:29.861Z","updated_at":"2025-10-20T12:49:41.875Z","avatar_url":"https://github.com/datamgmt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Music Chart Downloader\n\nMusic Chart Downloader (mcd.py) by David M Walker\n\n(c) 2024 Data Management \u0026 Warehousing\n\nExtract chart data from chart websites and store in files\n\nCurrently supports OfficialCharts.com Singles \u0026 Albums charts\n\n## Overview\n\n* This utility downloads the charts in html format from OfficialCharts.com (https://www.officialcharts.com)\n* The script can download the UK Singles Chart or the UK Album Chart.\n* The download can be for a single week, a range of weeks or all historical charts.\n* It then writes out the data as either a json file or a csv file for use elsewhere.\n\n## Process\n\n* Download all the html files for the data range requested from the chart website\n* html files that have already been downloaded will not be re-downloaded\n* Parse the files for the chart entries\n* Write the files out in either a json or csv file \n* Charts can be written out as one file per week or one file for all data\n\n## Running the script\n\nDownload all UK Singles charts and create a single CSV file with all the data\n```\n./mcd.py\n```\n\nDownload the 2023 UK Album charts and write one JSON file per week\n\n```\n./mcd.py --chart uk-albums --startdate 20230101 --enddate 20231231 --output_type json --output_set weekly\n```\n\nHelp and options\n\n```\nusage: mcd.py [-h] [--chart {uk-singles,uk-albums}] [--startdate STARTDATE] [--enddate ENDDATE] [--datadir DATADIR]\n               [--output_type [{csv,json} ...]] [--output_set [{weekly,all} ...]]\n\nThe Music Chart Downloader\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --chart {uk-singles,uk-albums}\n                        Which music chart to download, (Default: uk-singles)\n  --startdate STARTDATE\n                        The first chart to download in YYYYMMDD format (Default: 19521114)\n  --enddate ENDDATE     The last chart to download in YYYYMMDD format (Default: 20240509)\n  --datadir DATADIR     Location of datafiles used in processing (Default: ./data)\n  --output_type [{csv,json} ...]\n                        Output file formats required (Default: ['csv'])\n  --output_set [{weekly,all} ...]\n                        Weekly charts and/or one large file (Default: ['all'])\n\n(c)2024 Data Management \u0026 Warehousing\n```\n\n## Directory Structure\n\n```\n.\n├── README.md                   # This file\n├── data                        # Data Firectories\n│   ├── csv                     # CSV Output files\n│   ├── html                    # Downloaded HTML Files\n│   └── json                    # JSON Output files\n├── mcdc.py                     # The script\n└── samples                     # sample html files to understand the structure \n    ├── uk-singles-chart.html\n    └── uk-singles-chart.png\n\n```\n\n## Available data field\n\n* chart_date e.g. 2024-04-26\n* chart_position e.g. 1\n* chart_artist e.g. AVA MAX\n* chart_title e.g. SWEET BUT PSYCHO\n* chart_movement e.g. 1\n* chart_peak e.g. 1\n* chart_weeks e.g. 12\n\n## CSV Format example\n\n```\nchart_date,chart_position,chart_artist,chart_title,chart_movement,chart_peak,chart_weeks\n19521114,1,AL MARTINO,HERE IN MY HEART,New,1,1\n19521114,2,JO STAFFORD,YOU BELONG TO ME,New,2,1\n19521114,3,NAT 'KING' COLE,SOMEWHERE ALONG THE WAY,New,3,1\n19521114,4,BING CROSBY,THE ISLE OF INNISFREE,New,4,1\n19521114,5,GUY MITCHELL,FEET UP (PAT HIM ON THE PO-PO),New,5,1\n19521114,6,ROSEMARY CLOONEY,HALF AS MUCH,New,6,1\n```\n\n## JSON Format example\n\n```\n[\n    {\n        \"chart_date\": \"20221230\",\n        \"chart_movement\": \"3\",\n        \"chart_position\": \"1\",\n        \"chart_artist\": \"MICHAEL BUBLE\",\n        \"chart_title\": \"CHRISTMAS\",\n        \"chart_peak\": \"1\",\n        \"chart_weeks\": \"105\"\n    },\n    {\n        \"chart_date\": \"20221230\",\n        \"chart_movement\": \"1\",\n        \"chart_position\": \"2\",\n        \"chart_artist\": \"TAYLOR SWIFT\",\n        \"chart_title\": \"MIDNIGHTS\",\n        \"chart_peak\": \"1\",\n        \"chart_weeks\": \"10\"\n    }\n]\n```\n\n## Performance \u0026 capacity\n\n* Downloading and processing one year of data takes around 20 seconds on good machine and fast network (see Build environment below)\n* If the files have already been downloaded the processing time is around 3 seconds for the same set of files\n* This is based on 100 entries per week and 52 entries\n* Historical charts had significantly fewer entries and so are faster\n* Processing a large data range to an 'all' file also consumes more memory\n* All of the 2023 singles charts create a file of around 250Kb\n* The earliest charts are in the 1950s so there are around ~4000 files to process all data for a single chart\n\n\n## To Do List\n\nPotential enhancements for an indeterminate future update\n\n* Add US Billboard Charts (e.g. URL https://www.billboard.com/charts/hot-100/2024-04-13/)\n* XML Support\n\n## Build environment \u0026 maintenance\n\n* This utility was written on an Apple M1 Ultra based Mac running Sonoma 14.4.1 and Python version 3.9.6..\n* Written and tested in May 2024 - note that data formats of the source may vary over time. causing the programme to fail.\n* This code is unmaintained.\n\n## Other code that has similar functionality\n* https://pypi.org/project/uk-charts-api\n* https://medium.com/@caineosborne/analysing-uk-chart-history-1956-to-2017-6fec0ecc991b\n* https://www.markhneedham.com/blog/2020/01/04/quick-graph-uk-official-charts/\n\n## Acknowldgements\n* https://github.com/Prokopp for unwittingly being a sounding board \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatamgmt%2Fmusic-chart-downloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatamgmt%2Fmusic-chart-downloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatamgmt%2Fmusic-chart-downloader/lists"}