==Introduction== The root is `https://tools.wmflabs.org/mediaplaycounts/api`. The current version is 1. The version number will increase as backwards-incompatible changes are made. As such, this is the documentation for version 1, located at `https://tools.wmflabs.org/mediaplaycounts/api/1`. As with most trendy web APIs, parameters are sequential (i.e. the key is implied) and separated by forward slashes. ==FilePlaycount== `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount` The FilePlaycount group of methods returns metrics on a single Commons file. For the `filename` parameter, you should not include the `File:` prefix. You can use spaces or underscores in filenames. The `date` parameter and its variants `start_date` and `end_date` must take the format `YYYYMMDD`. ===date=== `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/date//` Returns play counts for an individual file on an individual date. `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/date/How_Wikipedia_contributes_to_free_knowledge.webm/20160201` returns ``` [ { "filename": "How_Wikipedia_contributes_to_free_knowledge.webm", "count": 48, "date": "20160201" } ] ``` ===date_range=== `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/date_range///` Returns play counts for an individual file through a range of dates, inclusive. The start date must be chronologically earlier than the end date. `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/date_range/How_Wikipedia_contributes_to_free_knowledge.webm/20160201/20160203` returns ``` { "total": 156, "details": [ { "filename": "How_Wikipedia_contributes_to_free_knowledge.webm", "count": 48, "date": "20160201" }, { "filename": "How_Wikipedia_contributes_to_free_knowledge.webm", "count": 36, "date": "20160202" }, { "filename": "How_Wikipedia_contributes_to_free_knowledge.webm", "count": 72, "date": "20160203" } ] } ``` ===last_30=== `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/last_30/` A shortcut for a `date_range` lookup for the last 30 days, starting with yesterday and going back for a total of 30 days of data. Note that this function will not work until the initial ingest of data into the database is complete. `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/last_30/How_Wikipedia_contributes_to_free_knowledge.webm` ===last_90=== `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/last_90/` A shortcut for a `date_range` lookup for the last 90 days, starting with yesterday and going back for a total of 90 days of data. Note that this function will not work until the initial ingest of data into the database is complete. `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/last_90/How_Wikipedia_contributes_to_free_knowledge.webm` ==CategoryPlaycount== `https://tools.wmflabs.org/mediaplaycounts/api/1/CategoryPlaycount` The CategoryPlaycount group of methods returns metrics for a category of Commons media files, traversing subcategories up to a defined depth. Each method within this group of methods allows you to define the subcategory depth optionally as the last parameter; if it is not included it will default to 9. ===date=== `https://tools.wmflabs.org/mediaplaycounts/api/1/CategoryPlaycount/date///` Returns play counts for all the files in a category on a given date, including subcategories. The depth of traversal can be optionally included as a last parameter but defaults to 9. `https://tools.wmflabs.org/mediaplaycounts/api/1/CategoryPlaycount/date/Ebolavirus_CDC_videos/20150101` returns ``` { "total": 232, "details": [ { "filename": "Donning_PPE-_Engage_Trained_Observer_CDC02.webm", "details": { "filename": "Donning_PPE-_Engage_Trained_Observer_CDC02.webm", "count": 10, "date": "20150101" } }, { "filename": "Donning_PPE-_Inspect_PPE_Prior_to_Donning_CDC04.webm", "details": { "filename": "Donning_PPE-_Inspect_PPE_Prior_to_Donning_CDC04.webm", "count": 9, "date": "20150101" } }, { "filename": "Donning_PPE-_Introduction_CDC01.webm", "details": { "filename": "Donning_PPE-_Introduction_CDC01.webm", "count": 53, "date": "20150101" } }, {...} ] } ``` ===date_range=== `https://tools.wmflabs.org/mediaplaycounts/api/1/CategoryPlaycount/date_range////` Returns play counts for a category of files, including subcategories, up to a defined depth, through a range of dates, inclusive. The start date must be chronologically earlier than the end date. The depth of traversal can be optionally included as a last parameter but defaults to 9. `https://tools.wmflabs.org/mediaplaycounts/api/1/CategoryPlaycount/date_range/Ebolavirus_CDC_videos/20150101/20150102` returns ``` { "total": 526, "details": [ { "total": 25, "filename": "Donning_PPE-_Engage_Trained_Observer_CDC02.webm", "details": { "total": 25, "details": [ { "filename": "Donning_PPE-_Engage_Trained_Observer_CDC02.webm", "count": 10, "date": "20150101" }, { "filename": "Donning_PPE-_Engage_Trained_Observer_CDC02.webm", "count": 15, "date": "20150102" } ] } }, { "total": 19, "filename": "Donning_PPE-_Inspect_PPE_Prior_to_Donning_CDC04.webm", "details": { "total": 19, "details": [ { "filename": "Donning_PPE-_Inspect_PPE_Prior_to_Donning_CDC04.webm", "count": 9, "date": "20150101" }, { "filename": "Donning_PPE-_Inspect_PPE_Prior_to_Donning_CDC04.webm", "count": 10, "date": "20150102" } ] } }, {...} ] } ``` ===last_30=== `https://tools.wmflabs.org/mediaplaycounts/api/1/CategoryPlaycount/last_30//` A shortcut for a `date_range` lookup for the last 30 days, starting with yesterday and going back for a total of 30 days of data. Note that this function will not work until the initial ingest of data into the database is complete. `https://tools.wmflabs.org/mediaplaycounts/api/1/CategoryPlaycount/last_30/Ebolavirus_CDC_videos` ===last_90=== `https://tools.wmflabs.org/mediaplaycounts/api/1/CategoryPlaycount/last_90//` A shortcut for a `date_range` lookup for the last 90 days, starting with yesterday and going back for a total of 90 days of data. Note that this function will not work until the initial ingest of data into the database is complete. `https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/last_90/Ebolavirus_CDC_videos` ==AskCommons== `https://tools.wmflabs.org/mediaplaycounts/api/1/AskCommons` The AskCommons group of methods are helper methods used internally that are available for others to use. ===find_subcategories=== `https://tools.wmflabs.org/mediaplaycounts/api/1/AskCommons/find_subcategories//` Returns a flat list of subcategories of the named category up to a specified subcategory depth (default is 9). `https://tools.wmflabs.org/mediaplaycounts/api/1/AskCommons/find_subcategories/National_Institute_for_Occupational_Safety_and_Health/1` returns ``` [ "John_Howard_(public_health_administrator)", "National_Institute_for_Occupational_Safety_and_Health_publications", "Power_tool_noise_and_vibration_tests_by_the_National_Institute_for_Occupational_Safety_and_Health" ] ``` ===find_media_files=== `https://tools.wmflabs.org/mediaplaycounts/api/1/AskCommons/find_media_files/` Returns a list of media files in a single category. **This does not traverse subcategories**. For the purposes of this method, a "media file" is a video or a sound recording; basically anything with a "play" button. `https://tools.wmflabs.org/mediaplaycounts/api/1/AskCommons/find_media_files/Wikipedia_App` returns ``` [ "Share-a-Fact_-_Music_Mix_V1.wav", "Share-a-Fact_on_the_Official_Wikipedia_Android_app.webm", "Share-a-Fact_on_the_Official_Wikipedia_iPhone_app.webm", "TopNav.webm", "Wikipedia_App_Test_1_-_iPad.ogv", "Wikipedia_App_Test_1_-_iPhone_4S.ogv", "Wikipedia_Mobile_5.0_for_iPhone_and_iPad.webm" ] ```