Source Code: https://aka.ms/absbeginnerdevwp8
PDF Version: https://aka.ms/absbeginnerdevwp8pdf

In this lesson we'll search for Flickr photos near the geocoordinate determined by our phone.

Many of the most popular phone apps have some interaction with web-based services ... so the app allows users to get at their own data that they've stored "in the cloud", or they provide access to data in order to make it available in some fresh new way.

As developers, we can access the web-based services programmatically IF they expose a web API. A web API is usually just an HTTP based method call ... the URL includes the input parameters of the method call, and the web API will return data back in some standard format. Nowadays, that is usually XML or JSON, JavaScript Object Notation.

Flickr is a great example of a web service we can leverage in our apps ... They have a vast amount of image data that we can search via their web-based API. All we need to do is call one of their methods and then parse the data they return to us.

Our game plan in this lesson:

1. We'll do a little investigation into the Flickr API to see how we can leverage it in our app
2. We'll get setup with Flickr so that we can make calls to their API, and get examples of how to call the method we want to utilize
3. We'll write code in our app to make calls to the Flickr API
4. When we get data back from our call to the Flickr API we'll figure out how to parse through it and actually obtain pictures that we can display in our app

This is a VERY long lesson, but it's crucial because it will serve as a proof of concept that our idea will actually work. We'll see how all the pieces come together and then the rest of the series will be adding improvements and refinements to what we do in this lesson.

1. Become familiar with the flickr API site, sign up for developer access

Navigate to: http://www.flickr.com/services/api/

This is the home page for Flickr's API.

Before you can take advantage of the API in your app, you'll need to sign up for a developer account.

There should be an obvious Sign Up link somewhere on the top of the page. I won't walk through that process ... it's likely to change over time. I was able to use my existing Yahoo! ID to sign up for a developer account. It's free and easy to get started, and you'll need your own account so that you can get your own API Key.

Most companies exposing APIs over the web want to ensure that developers are complying with their terms of service, or they want to track usage by app to better understand how their APIs are being leveraged. I suppose in extreme cases the company may want to shut down an app that is abusing the service. This is why most require a unique identification for the developer and the app through the use of an API Key. Flickr is no different.

To get an API Key for the AboutMe app, find the "API Key" somewhere on the Flickr API homepage.

This will list all of the API Keys you were granted for your apps. You'll need to use a different API Key for each app you intend to use with Flickr's API.

Ultimately, you want to create a new API Key by using the "Get Another Key" button.

For now, our app will not make any money, or it's not currently commercial but might be in the future, so choose "Apply for a Non-Commercial Key":

They want to learn more about the app you're building. You can copy my text if you want. You'll also need to agree to the terms and such:

When you fill out the form and click the SUBMIT button, you should receive your API Key.

Since I'm (probably) not supposed to legally reveal my key, I've blurred some of it out. Keep the Key and the Secret available. We'll need them later in this lesson.

Back on the main Flickr API page, you see a list of all the web callable APIs available on Flickr. You can literally perform any conceivable operations using Flickr as the backend storage and processor for your photos and create new applications that "mash up" Flickr's functionality with some of your own. That's exactly what we want to do ... combine Flickr's search capability for photos -- specifically searching for photos that were taken geographically in the same place the user of our app.

We want to learn more about the flickr.photos.search API ... how do we call it? What options can we send along to specify geolocation we want to search for?

2. Learning about Flickr's search API

When you find the API you're looking for (i.e., flickr.photos.search), click the hyperlink to learn more about that web API method.

On this page dedicated to the flickr.photos.search web method, we can see which input parameters are optional and which are required, the purpose / meaning of each parameter, the expected format of the parameter value, and so on.

We also can see a list of error codes returned by the web method to the caller ... this might help us interpret any error codes we receive.

There's also an "API Explorer : flickr.photos.search" link which takes us to a web page where we can experiment and learn how to call that particular web method.

By clicking the "Send" check box and supplying a value, we can see the format that our web method call should take. I'll input the a number of options such as the optional latitude and longitude for the John Hancock Center, and add optional text "observatory":

I'll add an optional radius of "1". I learn that the default "radius_units" are in kilometers, so by adding a "1" I'm saying "search within a 1 kilometer radius of the geocoordinate I'm specifying".

I also will choose to send the output of my query to JSON, the JavaScript Object Notation.

I'll choose the radio button next to "Sign call with no user token".

Once I've added my settings, I'll click the "Call Method..." button.

When I click the "Call Method..." button, a large textbox will appear beneath the button containing sample data in JSON format, as well as the URL that was constructed based on my selected options. Both of these will be important for me in just a moment.

3. Setting up our project to use the Flickr API

Back in my Visual Studio project, I'll need to prepare for making my first call into the Flickr API. I'll want to appropriately brand the app by changing the app and page titles. I'll just hardcode them this time and not use the resources file. I realize this will limit my app to just English speakers. I can always come back later and change this.

1. Change the Text attribute to "AROUND ME"
2. Change the Text attribute to "pictures near ..."

My next changes will be in the ContentPanel.

1. Add three RowDefinitions at various heights
2. Put a control in each of those new rows. I create a TextBlock called "ResultTextBlock" for row 1. I create an Image control called "FlickrImage" for row
3. Move the Map to row 3.

4. Programmatically calling the Flickr API via HTTP

My goal is to populate the Image control with a single image. Later, I'll add a search results page that can display all the results. For now, I just want to hack something together to figure out how to call into the Flickr search API programmatically and get results. I'll make it work correctly later.

1. I comment out the SetView() and instead use the Map's Center