apiheap.js easy lightweight open source

Download

apiheap.js is a JavaScript library that lets you make REST requests in under five lines of code.

Easy.

Apiheap.js is super easy to use. Start making your REST requests to a number of platforms, in just a few minutes.

Lightweight

Apiheap.js is only 6.13 kilobytes in size. Make quick and powerful requests, without compromising performance.

Open Source

Apiheap.js is completely opensource. View the code, make changes, and use it to your hearts content.

Usage

Setup

To use apiheap.js, include it after your </body> tag. Note that apiheap.js requires jQuery to function.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
<script src="js/apiheap.min.js"></script>

If you prefer, you can also use apiheap.js through a CDN.

<script src="https://cdn.rawgit.com/tash-had/apiheapjs/764562ed/apiheap.min.js"></script>
Hit 'How It Works' to get a gist of apiheap.js behind the scenes.

Get apiheap.js

How It Works

  • -Make an object for apiheap
  • -In parameters, specify platform name, and API key (if required)
  • -Platform Options: bitly, tumblr, imgur, reddit, youtube, openweathermap
  • -All platforms but reddit required some sort of API Key/Authentication
  • -Optionally, create a variable to store your data later.

var myObj = new apiheap("imgur", "IMGUR_CLIENT_ID"), myData;

  • -Use your object to call the method for the platform you specified in the previous step.
  • -The parameters for this method can vary for each platform. You can find these parameters by clicking the 'Details' button for your platform below.
  • In this example, the imgur() method can take three parameters;tag_name, opt_params, and is_topic.

var myObj = new apiheap("imgur", "IMGUR_CLIENT_ID"), myData;
myObj.imgur("Awesome", "top/all", true); //Look in topic 'Awesome', search top of all-time, request is a topic.

  • -After the code above has been executed through either a function or a page-load, your request has been made!
  • -Your response from the request lies in myObj.RESPONSE. You can use this data yourself, or parse it using apiheap.
  • -To parse your data using apiheap, simply use the parse() method of your object. Read about the parameters for your platform by pressing the 'Details' button for it below.
  • -In most cases, the parameter will be the item you want from the response.
  • -In almost all cases, the parse() method will return an array of the item you requested from each object in the response data.
  • -Ensure that you use the parse() method after the previous lines of code have surely executed. Otherwise, you will get an undefined error.

var myObj = new apiheap("imgur", "IMGUR_CLIENT_ID"), myData;
myObj.imgur("Awesome", "top/all", true); //Look in topic 'Awesome', search top of alltime, request is a topic.
function myFunction() {
    myData = myObj.parse("link"); //Requesting all 'links' from the objects in the response data.
    console.log(myData); } //Use the data (array)
    
Bitly
 //When myFunction() is triggered, bitlyLink will hold a short link for "https://google.ca"
var bitlyObj = new apiheap("bitly", "MY_AUTH_TOKEN"),bitlyLink;
bitlyObj.bitly("https://google.ca");
function myFunction() {
    bitlyLink = bitlyObj.parse(); console.log(bitlyLink);} 

Get Bitly Token

Tumblr
//When myFunction() is triggered, tumblrData will hold an array containing URL's of the 50 post's fetched. 
var tumblrObj = new apiheap("tumblr", "MY_TUMBLR_KEY"), tumblrData;
tumblrObj.tumblr("myexampleblog.tumblr.com", null, "limit=50");
function myFunction() {
    tumblrData = tumblrObj.parse("post_url"); console.log(tumblrData);} 

Get Tumblr Key

Tumblr Details

myObj.tumblr()
  • This method can take three parameters, and the first is required.
  • Format: myObj.tumblr("BLOG_URL", "POST_TYPE", "REQUEST_PARAMS")
  • BLOG_URL: Eg. "myblog.tumblr.com" or "myblog.com"
  • POST_TYPE: If left blank or null, the request will fetch all post types. Click here for a full list of post types.
  • REQUEST_PARAMS: If left blank, the request will fetch the last 20 posts from the blog. Options include "tag", "limit" among others. Click here for a full list.
  • After this is executed, your response will be in myObj.RESPONSE. You can use the data raw, or parse it using the function below.
myObj.parse()
  • This method takes one parameter; the item you want.
  • Format: myObj.parse("MY_ITEM");
  • MY_ITEM: the item you would like. If left blank or null, the function will return an array of posts from the request, which you can use. Item requests vary for each post. For example, audio posts will have properties like "track_name", or "plays", both of which photo posts do not have. When making the request in the myObj.tumblr() method, if you specified a POST_TYPE, this will not be an issue since all the posts in the response will be of the same type. However, if you did not specify a POST_TYPE, the post types in the response can vary. The parse() method returns an array of the item you requested from each post in the response. If the response posts have varying POST_TYPES, and you requested an item that some posts do not have, the array will have an undefined value pushed to it. Posts that do have the requested item, will have the value of that item pushed to the the array as usual. A full chart of properties of the response, and properties for each type of post can be seen here. (Everything under the "Response Field" columns can be used for the MY_ITEM parameter). A chart of properties common to all posts can be seen under the 'Responses' section here. For information about the blog, you can set this parameter to "blog_info", and you will recieve an object containing the info. You can also set this as "photos_url", and get an array of direct links to images in all photo posts from the response.

Imgur
//When myFunction() is triggered, imgurData will hold an array of links from the fetched data.  
var imgurObj = new apiheap("imgur", "MY_CLIENT_ID"), imgurData;
imgurObj.imgur("cats", "top/all");
function myFunction() {
    imgurData = imgurObj.parse("link"); console.log(imgurData); }

Get Imgur Client ID

Imgur Details

myObj.imgur()
  • This method can take three parameters, all of which are optional.
  • Format: myObj.imgur("TAG_NAME", "OPT_PARAMS", IS_TOPIC);
  • If all parameters are left blank, the request will fetch posts from the front page of Imgur.
  • TAG_NAME: is the tag name of the posts you'd like to fetch.
  • OPT_PARAMS: lets you specify a number of things about the posts your are fetching. You can sort the request by entering "viral", "top", or "time" in this parameter; you can also enter "rising" if your request was for a topic. If you entered "top" in the perameter, you can set a range with "top/day", "top/week", "top/month", "top/year", or "top/all". In all cases, you can specify a page number by trailing "page/NUMBER" at the end of your OPT_PARAMS value. For example: "top/all/page/3" or "page/3". You can also use this parameter to search in subreddit galleries, albums, and more, with r/SUBREDDIT_NAME, a/ALBUM_ID, etc. If you are doing this, set the first perameter to null. For example to search for the top images of all time in the "funny" subreddit gallery, you would write myObj.imgur(null, "r/funny/top/all"); Note that the first, and last character of this parameter can never be a slash.
  • IS_TOPIC: this is pretty self explanatory. Enter true if you are searching in a User-Submitted section (topic). Note that if you are searching in a topic, the first perameter (TAG_NAME) will be required, and its value should be the topic name.
myObj.parse()
  • This method takes one parameters; the item you'd like.
  • Format: myObj.parse("MY_ITEM");
  • MY_ITEM: Pass in the item you want from all of the fetched posts. You can set this parameter to anything under the 'Key' column in this chart. This function will return an array of the item you requested in each post from the response. If left blank, the function will return an array of all posts in the response.

Reddit
//When myFunction() is triggered, redditData will hold an array of URL's from post's fetched.   
var redditObj = new apiheap("reddit"), redditData;
redditObj.reddit("funny", "new", "t=week&limit=50");
function myFunction() {
    redditData = redditObj.parse("url"); console.log(redditData);} 

Reddit Details

myObj.reddit()
  • This method can take three parameters, all of which are optional.
  • Format: myObj.reddit("SUBREDDIT_NAME", "SORT", "OPT_PARAMS");
  • SUBREDDIT_NAME: the name of the subreddit you'd like to search. If left blank, the request will default to the front page.
  • SORT: this lets you specify many details about your request. If you are searching a subreddit, you can enter "new", "rising", "controversial", "top", "gilded" or "promoted". You can also use this parameter for other things, like searching subreddits. For example, myObj.reddit(null, "subreddits/popular"); will search for popular subreddits.
  • OPT_PARAMS: Use this parameter to add more specifics to your request. You can see a list of common parameters at the very top of this page. You can also see this chart for a list of things you can place in this parameter. In the following example, we use the second and third parameters to get results with a search query. myObj.reddit(null, "search", "q=kittens&limit=10");
myObj.parse()
  • Format: myObj.parse(MY_ITEM);
  • MY_ITEM: If left blank, the function will return an array of the posts fetched. You can use this parameter to specify what item you'd like from the response. You can enter anything under the 'name' column of this chart if you searched listings in a subreddit. Use this chart if you searched subreddit details. You can leave this blank to get an array of the posts, then browse through the properties yourself if you prefer.
Fetch Reddit Comments

    var redditObj = new apiheap("reddit"), redditData;
    /* Subreddit is optional. Defaults to /r/all. 2nd and 3rd parameters are required.
    This code will return the most recent comments from /r/cats containing "funny" */
    redditObj.reddit("cats", "comments", "funny&limit=50");
    function myFunction() {
        redditData = redditObj.parse("comments"); console.log(redditData);}
YouTube
//When myFunction() is triggered, ytData will hold an array of YouTube links from videos/playlists fetched.  
var ytObj = new apiheap("youtube", "MY_API_KEY"), ytData=[];
ytObj.youtube("search", "snippet", "q=cat videos");
function myFunction() {
    ytData = ytObj.parse(ytObj.RESPONSE, "vid_links"); console.log(ytData);}

Get YouTube API Key

YouTube Details
myObj.youtube()

  • This method perfroms list methods using the YouTube data API.
  • Format: myObj.youtube(TYPE, PART, OPT_PARAMS, PAGE_TOKEN);
  • TYPE: Enter the type of activity you wish to perform. Examples include "search" to make a search query or "playlists" to search playlists. A full list of resource types can be found here. Remember that type must be able to use list methods.
  • PART: This is a required parameter for the list method. The value of this parameter can vary depending on which resource type you're requesting. To see which parameters you can use, go to this link, scroll down to your resource type, and click the "list" method on the chart under your resource type. There, you'll see a chart with all the values you can enter for the PART parameter.
  • OPT_PARAMS: This parameter lets you specify more information about your request. You can find a list of all the optional parameters you can specify in the same chart you used to choose a value for the PART parameter.
  • PAGE_TOKEN: This parameter is not required and will be discussed further down.
  • Examples:
  • myObj.youtube("search", "snippet", "q=cat videos"); //Requesting results from a search query for 'cat videos'
  • myObj.youtube("playlists", "snippet", "channelId=CHANNEL_ID"); //Requesting playlists in a channel
myObj.parse()
  • Format: myObj.parse(DATA, ITEM);
  • DATA: This is the response from your request (stored in myObj.RESPONSE).
  • ITEM: This is the item you want from the results. Your options for this parameter are: "type", "vid_links", "vid_ids", "vid_dates", "vid_titles", "vid_thumbnails", "chan_links", "chan_ids", "chan_names" or "vid_descriptions". All of those are pretty self-explanatory. The function will return an array of the item you requested from each video in the response. This value is required, and will return an error if left blank.
    Note: If you're using the id's to construct embed links for an iFrame, know that playlist id's begin with 'PL.' To embed playlists, your iFrame source should be in the format: "https://www.youtube.com/embed/?list=MY_ID" for videos, it is the same but remove '?list='. To identify playlist id's from an array of id's, use JavaScripts's substr() function.
Getting More Pages of Results
  • The YouTube API only returns the first page of videos when you make a request. Each response contains a "nextPageToken" which is the token you can use to get results from the next page in your query. To do this, have a loadMore() function, which will use the nextPageToken to make another request. Example:
  • //Make object, and use youtube() method to make request for 'cats' search query. Also make variable to hold data. 
    var myObj = new apiheap("youtube", "MY_API_KEY"), query_results = [];
    myObj.youtube("search", "snippet", "q=cats");
    //Make loadMore() function to first push request response to query_results, then make another request using the youtube() method - this time, including a fourth parameter (PAGE_TOKEN). Enter pageToken(myObj.MY_RESPONSE) as the value for the fourth parameter.  
    function loadMore() {
        query_results.push(myObj.RESPONSE);
        myObj.youtube("search", "snippet", "q=cats", pageToken(myObj.RESPONSE));}
    //query_results will be an array of responses (depending on how many times loadMore() was triggered). Use the parse() method, and pass in query_results as the data, along with an request item to parse data from the responses. 
    function myFunction() {
        console.log(myObj.parse(query_results, "vid_links"));}
    

OpenWeatherMap
//When myFunction() is triggered, weatherData will hold an object with information from the response.  
var weatherObj = new apiheap("openweathermap", "MY_API_KEY"), weatherData;
weatherObj.weather("toronto");
function myFunction() {
    weatherData = weatherObj.parse("main"); console.log(weatherData);}

Get OpenWeatherMap Key

OpenWeatherMap Details

myObj.weather()
  • Format: myObj.weather("CITY", "CUSTOM");
  • CITY: Enter the city for the weather data you wish to fetch. Optionally, you can enter the country code also. Eg. "toronto, ca" or "london, uk"
  • CUSTOM: If you do not wish to search weather by city, you can leave the first parameter null and enter a custom request here. You can look at other methods here. Example: myObj.weather(null, "zip=XXXXXX, ca")
myObj.parse()
  • Format: myObj.parse("ITEM");
  • ITEM: See a full list of items by clicking here (look under the 'Parameters' section). For main whether information, enter "main" for this perameter.

Users

YouWork

YouWork is an open-source Chrome extension that aims to minimize distractions on YouTube by redirecting YouTube to YouWork - a distraction free version. YouWork uses apiheap.js to fetch YouTube videos and video data.

Internet-Thoughts

Check out Internet-Thoughts!

Internet-Thoughts

Internet-Thoughts is an open-source sentiment analysis tool created at Yale University for YHack 2016. Internet-Thoughts uses Apiheap.js (and other methods) to fetch data on any given topic based on a query. Internet-Thoughts then analyzes this data using a built-in sentiment-analysis engine, which calculates the average positivity/negativity within references of that topic.