aping-plugin-youtube

[logo]: http://aping.io/logo/320/aping-plugin.png "apiNG Plugin" ![apiNG][logo] [![Join the chat at https://gitter.im/JohnnyTheTank/apiNG](https://img.shields.io/badge/GITTER-join%20chat-green.svg)](https://gitter.im/JohnnyTheTank/apiNG?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![npm version](https://badge.fury.io/js/aping-plugin-youtube.png)](https://badge.fury.io/js/aping-plugin-youtube) [![Bower version](https://badge.fury.io/bo/apiNG-plugin-youtube.png)](https://badge.fury.io/bo/apiNG-plugin-youtube) **_apiNG-plugin-youtube_** is a [Youtube Data API v3](https://developers.google.com/youtube/v3/) plugin for [**apiNG**](https://github.com/JohnnyTheTank/apiNG). # Information * **Supported apiNG models: `social`, `video`** * This plugin supports the [`get-native-data` parameter](https://aping.readme.io/docs/advanced#parameters) * This plugin needs an [api key](#2-api-key) :warning: * Used promise library: [angular-youtube-api-factory](https://github.com/JohnnyTheTank/angular-youtube-api-factory) _(included in distribution files)_ # Documentation 1. [INSTALLATION](#1-installation) 1. Get file 2. Include file 3. Add dependency 4. Add plugin 2. [API KEY](#2-api-key) 1. Generate your `apiKey` 2. Insert your `apiKey` into `aping-config.js` 3. [USAGE](#3-usage) 1. Models 2. Requests 3. Rate limit ## 1. INSTALLATION ### I. Get file Install via either [bower](http://bower.io/), [npm](https://www.npmjs.com/), CDN (jsDelivr) or downloaded files: * `bower install apiNG-plugin-youtube --save` * `npm install aping-plugin-youtube --save` * use [CDN file](https://www.jsdelivr.com/projects/aping.plugin-youtube) * download [apiNG-plugin-youtube.zip](https://github.com/JohnnyTheTank/apiNG-plugin-youtube/zipball/master) ### II. Include file Include `aping-plugin-youtube.min.js` in your apiNG application ```html  <script src="bower_components/apiNG-plugin-youtube/dist/aping-plugin-youtube.min.js"></script>  <script src="node_modules/aping-plugin-youtube/dist/aping-plugin-youtube.min.js"></script>  <script src="//cdn.jsdelivr.net/aping.plugin-youtube/latest/aping-plugin-youtube.min.js"></script>  <script src="aping-plugin-youtube.min.js"></script> ``` ### III. Add dependency Add the module `jtt_aping_youtube` as a dependency to your app module: ```js angular.module('app', ['jtt_aping', 'jtt_aping_youtube']); ``` ### IV. Add the plugin Add the plugin's directive `aping-youtube="[]"` to your apiNG directive and [configure your requests](#ii-requests) ```html <aping template-url="templates/social.html" model="social" items="20" aping-youtube="[{'search':'funny cats'}]"> </aping> ``` ## 2. API KEY ### I. Generate your `apiKey` 1. Login on [console.developers.google.com](https://console.developers.google.com/) 2. Select a project, or create a new one. 3. In the sidebar on the left, expand APIs & auth. - Click APIs - In the list of APIs, make sure the status is **ON for the YouTube Data API v3** - Click Credentials - Click New credentials - Choose API key - Choose Browser key - Name and create your API Key ### II. Insert your `apiKey` into `aping-config.js` Open `js/apiNG/aping-config.js` in your application folder. It should be look like this snippet: ```js angular.module('jtt_aping').config(['$provide', function ($provide) { $provide.value("apingDefaultSettings", { apingApiKeys : { youtube : [ {'apiKey':'<YOUR_YOUTUBE_API_KEY>'}, ] //... } }); }]); ``` :warning: Replace `<YOUR_YOUTUBE_API_KEY>` with your youtube `apiKey` ## 3. USAGE ### I. Models Supported apiNG models | model | content | support | max items<br>per request | (native) default items<br>per request | |----------|---------|---------|--------|---------| | `social` | **videos** | full | `50` | `5` | | `video` | **videos** | full | `50` | `5` | **support:** * full: _the source platform provides a full list with usable results_ <br> * partly: _the source platfrom provides just partly usable results_ ### II. Requests Every **apiNG plugin** expects an array of **requests** as html attribute. #### Requests by Video | parameter | sample | description | |----------|---------|---------| | **`videoId`** | `cBLulx9f9vc` | Youtube `videoId` (comma seperated list) | Sample requests: * `[{'videoId':'cBLulx9f9vc'}, {'videoId':'tC76tIp0kBk'}]` * `[{'videoId':'cBLulx9f9vc,tC76tIp0kBk'}]` #### Requests by Channel | parameter | sample | default | description | optional | |----------|---------|---------|---------|---------| | **`channelId`** | `UCtQMmwBJGvINGU0lZ_GrZKQ` | | The `channelId` parameter indicates that the API response should only contain resources created by the channel<br>([Youtube Name to Channel ID Converter](http://johnnythetank.github.io/youtube-channel-name-converter/)) | no | | **`items`** | `20` | `5` | Items per request (`0`-`50`) | yes | | **`search`** | `happy` | | The `search` parameter specifies the query term to search for. Your request can also use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several search terms. For example, to search for videos matching either "boating" or "sailing", set the `search` parameter value to boating|sailing. Similarly, to search for videos matching either "boating" or "sailing" but not "fishing", set the `search` parameter value to boating|sailing -fishing | yes | | **`order`** | `rating` | `date` | The order parameter specifies the method that will be used to order resources in the API response. Use `date`, `rating`, `relevance`, `title`, `videoCount`, `viewCount`, (`$RANDOM`) | yes | Sample requests: * `[{'channelId':'UCtQMmwBJGvINGU0lZ_GrZKQ'}, {'channelId':'UC2pmfLm7iq6Ov1UwYrWYkZA'}]` * `[{'channelId':'UC37PFGlxWgx4tU6SlhPCdCw', 'items':10, 'search':'prank'}]` #### Requests by Playlist | parameter | sample | default | description | optional | |----------|---------|---------|---------|---------| | **`playlistId`** | `PLykXdRRd47IX_5gUChdhDjgKmQyZtRrC_` | | The `playlistId` parameter indicates that the API response should only contain resources containing in the playlist | no | | **`items`** | `20` | `5` | Items per request (`0`-`50`) | yes | Sample requests: * `[{'playlistId':'PLXkE1kzapj4a9oWMggQ0i682chTam-I98'}, {'playlistId':'PL0XHkAy96suU3u6rx8S-NBEaHBgqsHTck'}]` * `[{'playlistId':'PL0XHkAy96suU3u6rx8S-NBEaHBgqsHTck', 'items':10}]` #### Requests by Search | parameter | sample | default | description | optional | |----------|---------|---------|---------|---------| | **`search`** | `music` | | The `search` parameter specifies the query term to search for. Your request can also use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several search terms. For example, to search for videos matching either "boating" or "sailing", set the `search` parameter value to boating|sailing. Similarly, to search for videos matching either "boating" or "sailing" but not "fishing", set the `search` parameter value to boating|sailing -fishing | no | | **`items`** | `20` | `5` | Items per request (`0`-`50`) | yes | | **`order`** | `rating` | `date` | The order parameter specifies the method that will be used to order resources in the API response. Use `date`, `rating`, `relevance`, `title`, `videoCount`, `viewCount`, (`$RANDOM`) | yes | | **`lat`** | `-13.163333` | | Defines a circular geographic area and also restricts a search to videos that specify, in their metadata, a geographic location that falls within that area. | yes | | **`lng`** | `-72.545556` | | Defines a circular geographic area and also restricts a search to videos that specify, in their metadata, a geographic location that falls within that area. | yes | | **`distance`** | `1km` | `5000m` | The parameter value must be a floating point number followed by a measurement unit. Valid measurement units are `m`, `km`, `ft`, and `mi`. (valid values: `1500m`, `5km`, `10000ft`, and `0.75mi`) The API does not support values larger than 1000 kilometers. | yes | Sample requests: * `[{'search':'eagles'}, {'search':'Thomas Müller'}, {'search':'prank'}]` * `[{'search':'machu picchu', 'lat':'-13.163333', 'lng':'-72.545556', 'distance':'5km'}]` #### Requests by Coordinates | parameter | sample | default | description | optional | |----------|---------|---------|---------|---------| | **`lat`** | `-13.163333` | | Defines a circular geographic area and also restricts a search to videos that specify, in their metadata, a geographic location that falls within that area. | no | | **`lng`** | `-72.545556` | | Defines a circular geographic area and also restricts a search to videos that specify, in their metadata, a geographic location that falls within that area. | no | | **`distance`** | `1km` | `5000m` | The parameter value must be a floating point number followed by a measurement unit. Valid measurement units are `m`, `km`, `ft`, and `mi`. (valid values: `1500m`, `5km`, `10000ft`, and `0.75mi`) The API does not support values larger than 1000 kilometers. | yes | | **`order`** | `rating` | `date` | The order parameter specifies the method that will be used to order resources in the API response. Use `date`, `rating`, `relevance`, `title`, `videoCount`, `viewCount`, (`$RANDOM`) | yes | | **`items`** | `20` | `5` | Items per request (`0`-`50`) | yes | Sample requests: * `[{'lat':'-13.163333', 'lng':'-72.545556', 'distance':'5km'}]` ### III. Rate limit Visit the official Youtube Data API documentations: [Quota usage](https://developers.google.com/youtube/v3/getting-started#quota) # Licence MIT