Page MenuHomePhabricator
Paste P4339

Media Playcounts API documentation
ActivePublic

Authored by harej-NIOSH on Oct 31 2016, 10:34 PM.
==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.
`https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/last_30/How_Wikipedia_contributes_to_free_knowledge.webm`
results in, when run on 2 November 2016,
```
{
"details": [
{
"date": "20161003",
"count": 55,
"filename": "How_Wikipedia_contributes_to_free_knowledge.webm"
},
{
"date": "20161004",
"count": 76,
"filename": "How_Wikipedia_contributes_to_free_knowledge.webm"
},
{...},
{
"date": "20161101",
"count": 44,
"filename": "How_Wikipedia_contributes_to_free_knowledge.webm"
}
],
"total": 1859
}
```
===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.
`https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/last_90/How_Wikipedia_contributes_to_free_knowledge.webm`
results in, when run on 2 November 2016,
```
{
"details": [
{
"date": "20160804",
"count": 27,
"filename": "How_Wikipedia_contributes_to_free_knowledge.webm"
},
{
"date": "20160805",
"count": 31,
"filename": "How_Wikipedia_contributes_to_free_knowledge.webm"
},
{...},
{
"date": "20161101",
"count": 44,
"filename": "How_Wikipedia_contributes_to_free_knowledge.webm"
}
],
"total": 5371
}
```
==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 method currently does not work for inexplicable reasons.**
`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 method currently does not work for inexplicable reasons.**
`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"
]
```

Event Timeline

harej-NIOSH updated the paste's language from autodetect to remarkup.
harej-NIOSH updated the paste's language from remarkup to text.
harej-NIOSH edited the content of this paste. (Show Details)Nov 2 2016, 10:54 PM
harej-NIOSH added a subscriber: MusikAnimal.

@harej-NIOSH @Harej

Hi James,
the following tool (https://tools.wmflabs.org/commons-video-clicks/index.html) to track video clicks uses the API in this documentation. Unfortunately the usage of the API returns the following page when entering this link: https://tools.wmflabs.org/mediaplaycounts/api/1/FilePlaycount/date_range/How_Wikipedia_contributes_to_free_knowledge.webm/20160201/20160203

Thus the tool does not work and some people started to use this tool and would be happy to continue using it.

Do you have any idea how this problem can be solved?

Thanks in advance!

FYI: @Tobi_WMDE_SW

MusikAnimal added a comment.EditedJan 23 2018, 5:54 PM

@Stefan_Schneider_WMDE It's a little known secret, but there's also https://tools.wmflabs.org/mediaviews

I never have completely finished it, so beware there may be bugs (and categories don't work yet). I'm going to try to finish it soon... but perhaps what's there will be enough to hold you off in the meantime :)

Clarification: the above tool is using Harej's new API, which is located at https://partnermetrics.wmflabs.org/mediaplaycounts/api