Skip to content
This repository

An easy-to-use PHP Class for accessing Instagram's API.

branch: master

Merge pull request #32 from brunohoff/master

Fix URL encoding on login request
latest commit d13b952fea
Christian Metz authored
Octocat-spinner-32 example - Added locations endpoint November 20, 2013
Octocat-spinner-32 README.markdown Added code example February 04, 2014
Octocat-spinner-32 composer.json Added composer February 13, 2014
Octocat-spinner-32 instagram.class.php Fix URL encoding on login request February 13, 2014
Octocat-spinner-32 license.txt Version 2.0 update December 24, 2013

Image Instagram PHP API V2


A PHP wrapper for the Instagram API.
Feedback or bug reports are appreciated.

Supports Instagram video responses.


  • PHP 5.2.x or higher
  • cURL
  • Registered Instagram App

Get started

Register your application with Instagram, and receive your OAuth client_id and client_secret.
Take a look at the uri guidlines before registering a redirect URI.

A good place to get started is the example App.

Initialize the class

    require_once 'instagram.class.php';

    $instagram = new Instagram(array(
      'apiKey'      => 'YOUR_APP_KEY',
      'apiSecret'   => 'YOUR_APP_SECRET',
      'apiCallback' => 'YOUR_APP_CALLBACK'

    echo "<a href='{$instagram->getLoginUrl()}'>Login with Instagram</a>";

Authenticate user (OAuth2)

    // Grab OAuth callback code
    $code = $_GET['code'];
    $data = $instagram->getOAuthToken($code);

    echo 'Your username is: ' . $data->user->username;

Get user likes

    // Store user access token

    // Get all user likes
    $likes = $instagram->getUserLikes();

    // Take a look at the API response
    echo '<pre>';
    echo '<pre>';

All methods return the API data json_decode() - so you can directly access the data.

Available methods

Setup Instagram

new Instagram(<array>/<string>);

array if you want to authenticate a user and access its data:

new Instagram(array(
  'apiKey'      => 'YOUR_APP_KEY',
  'apiSecret'   => 'YOUR_APP_SECRET',
  'apiCallback' => 'YOUR_APP_CALLBACK'

string if you only want to access public data:

new Instagram('YOUR_APP_KEY');

Get login URL



Optional scope parameters:

Scope Legend Methods
basic to use all user related methods [default] getUser(), getUserFeed(), getUserFollower() etc.
relationships to follow and unfollow users modifyRelationship()
likes to like and unlike items getMediaLikes(), likeMedia(), deleteLikedMedia()
comments to create or delete comments getMediaComments(), addMediaComment(), deleteMediaComment()

Get OAuth token

getOAuthToken($code, <true>/<false>)

true : Returns only the OAuth token
false [default] : Returns OAuth token and profile data of the authenticated user

Set / Get access token

Stores access token, for further method calls:

Returns access token, if you want to store it for later usage:

User methods

Public methods

  • getUser($id)
  • searchUser($name, <$limit>)
  • getUserMedia($id, <$limit>)

Authenticated methods

  • getUser()
  • getUserLikes(<$limit>)
  • getUserFeed(<$limit>)
  • getUserMedia(<$id>, <$limit>)
    • if an $id isn't defined, it returns the media of the logged in user

Sample responses of the User Endpoints.

Relationship methods

Authenticated methods

  • getUserFollows($id, <$limit>)
  • getUserFollower($id, <$limit>)
  • getUserRelationship($id)
  • modifyRelationship($action, $user)
    • $action : Action command (follow / unfollow / block / unblock / approve / deny)
    • $user : Target user id
    // Follow the user with the ID 1574083
    $instagram->modifyRelationship('follow', 1574083);

Please note that the modifyRelationship() method requires the relationships scope.

Sample responses of the Relationship Endpoints.

Media methods

Public methods

  • getMedia($id)
  • getPopularMedia()
  • searchMedia($lat, $lng, <$distance>, <$minTimestamp>, <$maxTimestamp>)
    • $lat and $lng are coordinates and have to be floats like: 48.145441892290336,11.568603515625
    • $distance Radial distance in meter (default is 1km = 1000, max. is 5km = 5000)
    • $minTimestamp All media returned will be taken later than this timestamp (default: 5 days ago)
    • $maxTimestamp All media returned will be taken earlier than this timestamp (default: now)

Sample responses of the Media Endpoints.

Comment methods

Public methods

  • getMediaComments($id)

Authenticated methods

  • addMediaComment($id, $text)
    • restricted access: please email apidevelopers[at] for access
  • deleteMediaComment($id, $commentID)
    • the comment must be authored by the authenticated user

Please note that the authenticated methods require the comments scope.

Sample responses of the Comment Endpoints.

Tag methods

Public methods

  • getTag($name)
  • getTagMedia($name)
  • searchTags($name)

Sample responses of the Tag Endpoints.

Likes methods

Authenticated methods

  • getMediaLikes($id)
  • likeMedia($id)
  • deleteLikedMedia($id)

How to like a Media: Example usage
Sample responses of the Likes Endpoints.

All <...> parameters are optional. If the limit is undefined, all available results will be returned.

Instagram videos

Instagram entries are marked with a type attribute (image or video), that allows you to identify videos.

An example of how to embed Instagram videos by using Video.js, can be found in the /example folder.

Please note: Instagram currently doesn't allow to filter videos.


Each endpoint has a maximum range of results, so increasing the limit parameter above the limit won't help (e.g. getUserMedia() has a limit of 90).

That's the point where the "pagination" feature comes into play.
Simply pass an object into the pagination() method and receive your next dataset:

    $photos = $instagram->getTagMedia('kitten');

    $result = $instagram->pagination($photos);

Iteration with do-while loop.

Samples for redirect URLs

Registered Redirect URI Redirect URI sent to /authorize Valid? yes yes no yes no no yes

If you need further information about an endpoint, take a look at the Instagram API docs.

Example App


This example project, located in the example/ folder, helps you to get started.
The code is well documented and takes you through all required steps of the OAuth2 process.
Credit for the awesome Instagram icons goes to Ricardo de Zoete Pro.

More examples and tutorials:

Let me know if you have to share a code example, too.


Instagram 2.1 - 30/01/2014

  • update added min and max_timestamp to searchMedia()
  • update public authentication for getUserMedia() method
  • fix support for inconsistent pagination return type (relationship endpoint)

Instagram 2.0 - 24/12/2013

  • release version 2.0

Instagram 2.0 beta - 20/11/2013

  • feature Added Locations endpoint
  • update Updated example project to display Instagram videos

Instagram 2.0 alpha 4 - 01/11/2013

  • feature Comment endpoint implemented
  • feature New example with a fancy GUI
  • update Improved documentation

Instagram 2.0 alpha 3 - 04/09/2013

  • merge Merged master branch updates
    • update Updated documentation
    • bug / change cURL CURLOPT_SSL_VERIFYPEER disabled (fixes #6, #7, #8, #16)
    • feature Added cURL error message
    • feature Added limit to getTagMedia() method

Instagram 2.0 alpha 2 - 14/06/2013

  • feature Improved Pagination functionality
  • change Added distance parameter to searchMedia() method (thanks @jonathanwkelly)

Instagram 2.0 alpha 1 - 28/05/2012

  • feature Added Pagination method
  • feature Added User Relationship endpoints
  • feature Added scope parameter table for the getLoginUrl() method

Instagram 1.5 - 31/01/2012

  • release Second master version
  • feature Added Tag endpoints
  • change Edited the "Get started" example
  • change Now you can pass the getOAuthToken() object directly into setAccessToken()

Instagram 1.0 - 20/11/2011

  • release First public release
  • feature Added sample App with documented code
  • update New detailed documentation

Instagram 0.8 - 16/11/2011

  • release First inital released version
  • feature Initialize the class with a config array or string (see example)

Instagram 0.5 - 12/11/2011

  • release Beta version
  • update Small documentation


Copyright (c) 2011-2014 - Programmed by Christian Metz
Released under the BSD License.

Bitdeli Badge

Something went wrong with that request. Please try again.