Instagram API How to

Before you start, you’ll need to get an Instagram developer account at http://instagram.com/developer. You can log in with your regular Instagram account and just add the developer part onto it if you want. Once you’re signed up, create a new “Client” aka “App” (they seem to use those terms interchangeably). One of the fields it asks you to fill in is kind of confusing: “OAuth redirect_uri”. Just put a link to your website for now; it can be the same as what you put in the website URL field.

These instructions cover accessing public Instagram media. It's also possible to use the API to do things like upload photos, follow users, like photos, etc. Anything you'd have to be logged in to Instagram to do takes another level of authentication in the API -- we're keeping it simple and just viewing media.

For the new Client you registered, locate the Client ID from this page: http://instagram.com/developer/clients/manage/

###Building the URL To get data from Instagram, we'll need a URL. The URL will always include your API, but it also varies based on what data you want to retrieve. The beginning part of the URL is always the same.

https://api.instagram.com/v1/

The next part of the URL is based on the type of data you want to get -- photos, users, etc. Instagram calls these the API Endpoints. Open the Instagram API documentation and review the available endpoints. Find the endpoint for the type of data you’re requesting — popular photos, photos with a particular tag, etc.

The media endpoint URL starts with “media” and then has a second element which depends on what you want to do. To find the media near a certain location, for example, the endpoint is “media/search”. So the URL would start:

https://api.instagram.com/v1/media/search?

Everything after the question mark is where we put our custom parameters, like the location we want to search within. The available parameters are documented here: http://instagram.com/developer/endpoints/media/#get_media_search It turns out that search here is a location search and only takes a latitude and longitude as a location. To translate a place name to lat/long coordinates, try this tool.

Under media/search, the documentation gives you a sample URL:

https://api.instagram.com/v1/media/search?lat=48.858844&lng=2.294351&access_token=ACCESS-TOKEN

It has a latitude and longitude, but you’ll see in the documentation there are also parameters for time and distance. The last parameter is for your API key. In this example, it shows “access_token”, but you can use your CLIENT ID instead and skip having to generate an access token every time. So, your complete URL would be:

https://api.instagram.com/v1/media/search?lat=48.858844&lng=2.294351&client_id=MY-CLIENT-ID

If you plug in your client id and paste the above into the browser, you should get a bunch of JSON text back. (Or a very short piece of JSON if there’s an error.) Glancing through the JSON text, you’ll see a lot of the info you might want in there — a bunch of links to jpgs, the username, the number of likes, and so on. Paste the JSON text into http://www.jsoneditoronline.org to get a better look.

Notice in the documentation the button to the right of the URL that says Response — that will show you what you can expect the JSON to look like.