Page MenuHomePhabricator
Files F4681919

Media Playcounts API documentation
No One
Actions

Authored By
harej-NIOSH
Oct 31 2016, 10:34 PM
Size
8 KB
Referenced Files
None
Subscribers
None

Media Playcounts API documentation
View Options

==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/<filename>/<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/<filename>/<start_date>/<end_date>`
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/<filename>`
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/<filename>`
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/<category>/<date>/<depth=9>`
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/<category>/<start_date>/<end_date>/<depth=9>`
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/<category>/<depth=9>`
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/<category>/<depth=9>`
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/<category>/<depth=9>`
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/<category>`
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"
]
```

File Metadata

Mime Type
text/plain; charset=utf-8
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
4108604
Default Alt Text
Media Playcounts API documentation (8 KB)

Event Timeline

Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL