Get a free year on Tuts+ this month when you purchase a Siteground hosting plan from $3.95/mo
Imagine you've made the beautiful map a client requested; adding all sorts of interesting markers, pop-ups, custom overlays and photos. But then the client mentions they want to be able to add their own photos without either troubling you, or doing any coding themselves. This is where the Flickr API comes in very handy.
The Flickr API allows you to essentially use the Flickr website as your database or storage area for your photos. Using the Flickr API, you can grab your photos from Flickr and display them, among other places, on your Google map. Every time you or your client adds photos to your account on the Flickr website, your Google map is automatically updated.
If you take a look at the demo, the photos that appear when you click the ‘Smaller events’ button are being pulled from a Flickr account which I set up for this tutorial. Or, if you look at my Portsmouth History map, the photos that appear when you click on the Old Photographs button (right-hand menu) are all being drawn from Flickr.
The Flickr API actually lets you do much more than grab photos from your own account. It gives you the ability to create complex queries on the metadata, drawing photos from all Flickr users. This gives you an extremely powerful tool which you can put to all sorts of interesting and creative uses. The downside, however, is that the extensive capability of the API can make it a bit daunting if you've not used it before, and it can be difficult to know where to start. With this in mind, this tutorial focuses on the example of drawing photos from your own Flickr account, giving a complete walk-through of the process. Once you have the hang of this, you should be able to make good use of the rest of the API.
This tutorial builds on the previous tutorials, which covered getting creative with the Google Maps API and creating custom overlays, by explaining how you can link the Flickr API with the Google Maps API.
Quick Reminder About APIs
An API, or Application Programming Interface, is a fancy way of defining a set of commands, published by a company (e.g. Facebook, Twitter, You Tube, Flickr), which allow anyone to create a highly customized version of their content. When people talk about ‘mash-ups’ they mean they've used the API of two or more companies to combine content. There are literally thousands of these APIs around; take a look at the Programmable Web site for a list.
The first tutorial looked at how the Google Maps API will enable you to do all sorts of things, including customizing the colors, map markers, pop-up box style, level of detail, zoom level. The Flickr API is just as extensive.
Getting Started With the Flickr API
To get started with the Flickr API you need to create a Flickr account, then add a few photos to your account so you have something to work with. Try to use some pictures from different locations (this will be important later). The images used in this tutorial are available in the source files at the top of this page.
Note: If you use these images, please credit their original creators, listed at the foot of this page.
Once you have some content to play with, it’s time to get started with the API. These are a few key websites.
- Flickr API developers’ guide. This is kind of a ‘started guide’.
- Flickr API documentation. This lists all the API methods (i.e. everything you can do with the API), the formats you can use to request data, and the formats the data can be returned in. Bookmark this page!
- Flickr API help page.
Before you can get started, the first thing you need to do is to get your own API key. Make a note of these details; you'll need them later!
The ‘Hello World’ of the Flickr API
Take a look at this simple example; it uses the Flickr API to grab photos from the Flickr account I created for this tutorial. Instead of listing isolated code snippets here, it's more useful if you take a look at the code for the whole website to see how things work together. Go to the simple example, right-click on the page and select view source. Or download the source from the top of this page and pull it apart.
The comments within the source code provide a detailed explanation, but it’s worth giving a walk-through of a few key areas.
The most important thing to get your head around is how you access the Flickr API using a special URL. You construct this URL to 'ask' for the data you are after. The first part of this URL is –
You then add things to specify what you are after. The first thing you add is the method –
You then add the arguments and the format you need, which have an & sign between each one -
user_idargument is the account you want to draw the photos from. Use idGettr to work this out.
api_keyis the code you obtained in the previous step. You can construct this URL manually by looking at the documentation for your chosen method, e.g. flickr.people.getPublicPhoto, but this is a bit fiddly.
Fortunately, Flickr offers a link to a handy wizard (called API Explorer) at the bottom of each ‘method’ page. A word of warning though; by default the URL generated by the wizard has ‘nojsoncallback=1’ at the end. As we need to push the results into a function, in our case the end should be ‘nojsoncallback=?’ (See JSON response format for more details).
So, to construct your URL that calls the Flickr API, you need to:-
- Go to the Flickr API Documentation homepage and select the method (from the list on the right) that you want to use.
- Then on the ‘method’ page (e.g. flickr.people.getPublicPhoto), take a closer look at the description and the details to make sure this is the one for you. Then scroll right down to the bottom of the page and click on the API explorer link.
- On the API explorer page, fill in the relevant information about the arguments, and then scroll down. Select the JSON output. (More about output formats later). And, select ‘Do not sign call?’ as we are looking at public data. Then click the Call Method button (above).
- Take a look at the bottom of the screen now. You should see it’s presented you with the results of your query. And, right at the end, there’s the URL you need!
- If you copy this URL into your browser, you’ll actually see the result of the query. They are often a bit hard to read, but if you copy the results into the JSON Formatter then all will be revealed. As mentioned above, before using this URL to call Flickr from within your own web pages, alter the end to ‘nojsoncallback=?’, and remember to replace the
api_keyargument with your own key.
Capture the Results
Once you've constructed your URL that calls the Flickr API we need a way of capturing the results. We do this using the $.getJSON jQuery method. The $.getJSON method reads in data that's in the JSON format (e.g. below) and calls a function (in this case
displayImages1), which processes the data in some way (in this case displaying the images on a web page).
Wait - What Exactly is JSON?
While we are on the subject of JSON, it’s worth pointing out that JSON is just a way of formatting or structuring information so a computer can read it. If you look at the JSON output (above), you can start to see how the code is accessing each bit of the data. So, for example,
data.photos.photo (look in the
photo array in the JSON where most of the information is stored. Then, for example,
var photoID = item.id; is accessing the id element for each photo.
One Last Example: Kittens
Before carrying on, it’s worth taking a quick look at another example. Let’s embrace the internet’s primary purpose (i.e. sharing cat pictures) and find pictures tagged with the word ‘kitten’.
To maximize our kitten finding abilities, this time we want to search through photos uploaded by everyone. So the first step is to construct the Flickr API query, which looks like this -
This API call is using the flickr.photos.search method. This URL is then fed into the
$.getJSON method and processed in a similar way to the first example. Take a look at the live example to see the result. The source code is available from the link at the top of this page.
Once you've taken a look at both examples, have a go at using the API to grab your own images from your Flickr account and display them on a web page.
The Tip of the Iceberg!
Your first brush with the Flickr API should have equipped you with the key principles of how it works. However, it’s also likely you've started to notice how vast it is!
This isn't a bad thing as it provides you with an array of possibilities. Use the API documentation like a kind of ‘shopping list’. Take time to look through the methods (listed on the right of the API documentation home page) to see what’s on offer.
The beauty of Flickr is that you can edit all sorts of meta data for each photo.
The bit we are interested in here is the geographical location of each photo, and it’s easy to set this for each image:
- Log into your Flickr account.
- Click on ‘You’ in the top-left.
- Click on the menu icon (three little circles in a row) in the bottom-right.
- Click ‘Add to map’. Then follow the instructions on the screen. Flickr automatically works out and stores the latitude and longitude for each photo.
You need to repeat this process for each of your photos.
Creating a Google and Flickr Mashup
Once you’ve geotagged your photos in Flickr, you can display them on a Google map. Click here to see a live demo and then right-click to view the source code.
Similarly to the previous example, the comments within the source code give a detailed explanation. However, it’s worth highlighting a few key points. Firstly, to construct the URL that calls the Flickr API, we use the flickr.photos.search again. This time we included the arguments
extras=geo to make sure the latitude and longitude for each image are also included in the results. To see the results of the URL that calls the Flickr API, copy it (below) into your browser and then use JSON Formatter to see the output more clearly.
body tags, the Google Maps API is use to create the map itself.
You should be able to recreate something similar using your own images that you loaded into Flickr. The iTouchMap website is useful for working out what the center point of your map should be.
Flickr and Our UK Festivals Map
This is the kind of thing we are aiming for. If you click on the ‘Smaller events’ button you’ll see the images being drawn from Flickr.
For completeness I've also added images, which are not coming from Flickr, to the ‘main festival’ icons. Also, so you can see the different options in terms of pop-up boxes, I’ve used both the ‘info boxes’ (for the ‘main festivals’) and the default ‘info windows’ for the photos from Flickr.
This map was created by making a few tweaks to the code from the previous tutorial, and adding the code from the Google Maps and Flickr mashup (above). We first create a variable (
smallEventsToggle) to hold whether or not the 'small events' markers are currently showing. And, then create a new option in the
handelRequests function to deal with the situation when the 'small events' button (
smallEvents) is clicked. Finally, the code from the previous step is added and a few finishing touches made, such as changing the default map marker.
As usual, to spare you large snippets within the tutorial, the comments within the downloadable source code give a detailed explanation.
The next tutorial will look at optimization, responsive design, debugging and testing.
- Green Man Festival – by Nicholas Smale
- V-Festival - by Liam Swinney
- V-Festival - by Dylan J C
- Download – by Sezzles
- Bestival - by Mike Mantin
- Hop Farm Festival – by Gerardo Lazzari
- Strawberry Fields Festival - by remixyourface
- Wireless – by Surreal Name Given
- Lovebox – by Annie Mole
- Global Gathering – by Oli R
- Wilderness – by Andy Carter
- Beautiful Days – by Brian Marks
- Creamfields – by Gerardo Lazzari
- British Summer Time – by Andrea Sartorati
- Rewind – by Chris Osborne
- End of the road festival – by jaswooduk
- Y Not Festival - by Jo Jakeman
- Isle of Wight – by David Jones
- Reading Festival – by David Martyn Hunt
- Latitude – by markheybo
- Leeds Festival - by Richard Riley
- Secret Garden Party – by Wonderlane
- Glastonbury Festival – by wonker
- Glasgowbury – by Mike Mantin
- T in the Park – by Ian Oldham
- Rockness – by Ian Oldham
- Green map icons
The credits for the photos on the map markers themselves can be found at the end of the first tutorial.