Instajam

Instajam is a JavaScript wrapper for the Instagram API. You provide the access token, we provide the jam.

(And Instagram provides the gram. Or the pictures. Or... whatever.)

Version History

• 2012/9/10 - Version 1.0, initial release. Supports all GET endpoints (does NOT include adding/removing comments or likes, or setting relationships)

Getting Started

To use Instajam, just include it in your page. For now, Instajam also requires jQuery to facilitate JSONP requests.

<script src="lib/jquery.js"></script>
<script src="lib/instajam.js"></script>

Authentication

Instajam doesn't care how you do OAuth authentication. Want to handle it server-side and just pass the access token in? Cool. Would you rather do client-side authentication and pull your access token from a cookie or localStorage? Legit, brah. Instagram has documentation on their developer site to help you out. Regardless of how you do it, initialize Instajam like this:

<script type="text/javascript">
  $(function() {

    var INSTAJAM = new Instajam({
      access_token: 'ACCESS TOKEN',
      client_id: 'CLIENT ID'
    });

  });
</script>

Keep in mind, client_id is optional if you pass in access_token. However, if you just want to do some basic retrieval of media, like getting popular images (see below), then just the client_id will do. Awesome.

Get Some (Data)

After inializing, we're all set to request some information from Instagram. To get the authenticated users Instagram feed:

INSTAJAM.user.feed(function(feed) {  	
  // The object passed back, 'feed', will contain the data
  // passed back from the Instagram API.
});

The full set of endpoints included in Instajam are listed below, along with links to the descriptions of the endpoints in the Instagram developers documentation.

Endpoints

The official list of Instagram API endpoints has detailed descriptions as well as sample return data, so this documentation will not go into those details. Below you will find the endpoints that Instajam provides and how to call them.

Users and Relationships

Instajam.user.self(callback)

• Description: Returns basic information about the authenticated user.
• Endpoint: users/self
• Arguments:
  • callback(result): A callback function.

Instajam.user.feed(options, callback)

• Description: Returns the home feed of the authenticated user.
• Endpoint: users/self/feed
• Arguments:
  • options: A JSON object of options.
    • access_token
    • count
    • min_id
    • max_id
  • callback(result): A callback function.

Instajam.user.liked(options, callback)

• Description: Returns a list of media recently liked by the authenticated user.
• Endpoint: users/self/media/liked
• Arguments:
  • options (optional): A JSON object of options
    • count
    • max_like_id
  • callback(result): A callback function.

Instajam.user.get(user_id, callback)

• Description: Returns basic information about a user.
• Endpoint: users/[user-id]
• Arguments:
  • user_id: The user ID to fetch information for.
  • callback(result): A callback function.

Instajam.user.getRecent(user_id, options, callback)

• Description: Returns images recently uploaded by a user.
• Endpoint: users/[user-id]/media/recent
• Arguments:
  • user_id: The user ID to fetch information for.
  • options: A JSON object of options
    • count
    • max_timestamp
    • min_timestamp
    • max_id
    • min_id
  • callback(result): A callback function.

Instajam.user.search(term, options, callback)

• Description: Returns a list of user results for a given search term.
• Endpoint: users/search
• Arguments:
  • term: The search term string
  • options: A JSON object of options
    • count
  • callback(result): A callback function

Instajam.user.lookup(username, callback)

• Description: Returns basic information for the given username.
• Arguments:
  • username: The username string to look up.
  • callback(result): A callback function.

Instajam.user.follows(user_id, callback)

• Description: Returns a list of users the currently authenticated user follows.
• Endpoint: users/[user-id]/follows
• Arguments:
  • user_id: The user ID to fetch information for.
  • callback(result): A callback function.

Instajam.user.following(user_id, callback)

• Description: Returns a list of users followed by the currently authenticated user.
• Endpoint: users/[user-id]/followed-by
• Arguments:
  • user_id: The user ID to fetch information for.
  • _callback(result): A callback function.

Instajam.user.requests(callback)

• Description: Returns a list of pending follow requests for the currently authenticated user.
• Endpoint: users/self/requested-by
• Arguments:
  • callback(result): A callback function.

Instajam.user.getRelationship(user_id, callback)

• Description: Returns information about the relationship between the currently authenticated user and the given user ID
• Endpoint: users/[user-id]/relationship
• Arguments:
  • user_id: The user ID to fetch relationship information for.
  • _callback(result)

Media, Likes and Comments

Instajam.media.get(media_id, callback)

• Description: Returns information for a given media ID
• Endpoint: media/[media-id]
• Arguments:
  • media_id: The ID of the media to fetch information for.
  • callback(result): A callback function.

Instajam.media.search(options, callback)

• Description: Returns media matching the provided search parameters.
• Endpoint: media/search
• Arguments:
  • options: A JSON object of options.
    • lat (required)
    • lng (required)
    • min_timestamp
    • max_timestamp
    • distance (in meters. max is 5000)
  • callback(result): A callback function.

Instajam.media.popular(callback)

• Description: Returns media that is currently popular on Instagram.
• Endpoint: media/popular
• Arguments:
  • callback(result): A callback function.

Instajam.media.comments(media_id, callback)

• Description: Returns a list of comments for a piece of media.
• Endpoint: media/[media-id]/comments
• Arguments:
  • media_id: The ID of the media to fetch comments for.
  • callback(result): A callback function.

Instajam.media.likes(media_id, callback)

• Description: Retrieves 'likes' for a piece of media.
• Endpoint: /media/[media-id]/likes
• Arguments:
  • media_id: The ID of the media to retrieve 'likes' for.
  • callback(result): A callback function.

Tags

Instajam.tag.meta(tag_name, callback)

• Description: Requests metadata for a tag name.
• Endpoint: /tags/[tag-name]
• Arguments:
  • tag_name: The name of the tag to fetch metadata for.
  • callback(result): A callback function.

Instajam.tag.get(tag_name, options, callback)

• Description: Gets media for a tag name.
• Endpoint: /tags/[tag-name]/media/recent
• Arguments:
  • tag_name: The name of the tag to fetch media for.
  • options: A JSON object of options.
    • min_id
    • max_id
  • callback(result): A callback function.

Instajam.tag.search(search_term, callback)

• Description: Searches for a tag name.
• Endpoint: /tags/search
• Arguments:
  • search_term: The tag name to search for.
  • callback(result): A callback function.

Locations

Instajam.location.meta(location_id, callback)

• Description: Requests metadata for a location.
• Endpoint: /locations/[location-id]
• Arguments:
  • location_id: The ID of the location to fetch metadata for.
  • callback(result): A callback function.

Instajam.location.get(location_id, options, callback)

• Description: Gets media for a location.
• Endpoint: /locations/[location-id]/media/recent
• Arguments:
  • location_id: The ID of the location to fetch media for.
  • options: A JSON object of options.
    • max_timestamp
    • min_timestamp
    • min_id
    • max_id
  • callback(result): A callback function.

Instajam.location.search(options, callback)

• Description: Searches for locations.
  • Endpoint: /locations/search
  • Arguments:
    • options: A JSON object of options. Either "lat" and "lng", or "foursquare_v2_id" are required.
      • lat
      • lng
      • distance (in meters, max is 5000)
      • foursquare_v2_id
    • callback(result): A callback function.

Geographies

Instajam.geography.get(geography_id, options, callback)

• Description: Gets recent media from a user-defined geography. In order to fetch media for a geography, your app must have created it.
• Endpoint: /geographies/[geo-id]/media/recent
• Arguments:
  • geography_id: The ID of the geography to fetch media for.
  • options: A JSON object of options.
    • count
    • min_id
  • callback(result): A callback function.

Helper Functions

Instajam.nextPage(pagination_url, callback)

• Description: For some requests, Instagram will return a data.pagination key with a URL for the next page of results. This function facilitates making that request.
• Arguments:
  • pagination_url: The URL of the next page of results to fetch.
  • callback(result): A callback function.