Mobile Zone is brought to you in partnership with:

Den is a DZone Zone Leader and has posted 460 posts at DZone. You can read more from them at their website. View Full User Profile

Flickr API for Windows Phone 7 – Part 14 – People

10.20.2010
| 6750 views |
  • submit to reddit

Flickr is not only tied to pictures, but also to people – they are the main content providers. What if your friends have a Flickr account? Then, most likely you’d want to see what pictures they publish and the other way around. If that’s the case, then you need some functionality to look for people who are already registered, even if they are not on your contact list.

The Flickr API has 8 methods that can help you find people and take a look at the public content they publish via the service. These methods are:

•    flickr.people.findByEmail
•    flickr.people.findByUsername
•    flickr.people.getInfo
•    flickr.people.getPhotos
•    flickr.people.getPhotosOf
•    flickr.people.getPublicGroups
•    flickr.people.getPublicPhotos
•    flickr.people.getUploadStatus

The name of each method is pretty self-explanatory. Unlike the majority of methods on Flickr, all but two methods (flickr.people.getPhotos and flickr.people.getUploadStatus) in this set do not require authentication, therefore the only unique application-specific identifier you will need to pass is the API key.

So let’s look at code. First of all, in the existing Core folder create a class named People and make it static – I do not plan on instantiating this class – all requests will be made sequentially.

flickr.people.findByEmail

This is the method used to find someone by their email address. The only additional parameter required is the actual email address. When you are using this specific method, you cannot specify any additional details or use only parts of an email (e.g. *@hotmail.com) – a complete email address is required.

In the class itself, I created an instance of HelperDelegate and a property called PeopleQueryResult (will be used to store the final search result):

static HelperDelegate helperDelegateInstance;
public static string PeopleQueryResult {get;set;}

The actual implementation does not involve complex HTTP requests – it is a plain call to a URL with required parameters passed:

public static void FindByEmail (string apiKey, string email, HelperDelegate helperDelegate)
{
    helperDelegateInstance = helperDelegate;

    WebClient client = new WebClient();
    client.DownloadStringCompleted += new DownloadStringCompletedEventHandler(client_DownloadStringCompleted);
    string URL = string.Format("http://www.flickr.com/services/rest/?method=flickr.people.findByEmail&api_key={0}&format=json&find_email={1}",
            apiKey, email);

    client.DownloadStringAsync(new Uri(URL));
}

If I pass my email as the parameter, I will get this:

jsonFlickrApi({"user":{"id":"47289884@N03", "nsid":"47289884@N03", "username":{"_content":"Dennis K. Delimarsky"}}, "stat":"ok"})

Yep, that’s me – the method works correctly.

flickr.people.findByUsername

This method is executed exactly the same way as the previous one. All you have to do is change the method reference in the URL to the new name and instead of the find_email parameter, use username.

public static void FindByUsername(string apiKey, string username, HelperDelegate helperDelegate)
{
    helperDelegateInstance = helperDelegate;

    WebClient client = new WebClient();
    client.DownloadStringCompleted += new DownloadStringCompletedEventHandler(client_DownloadStringCompleted);
    string URL = string.Format("http://www.flickr.com/services/rest/?method=flickr.people.findByUsername&api_key={0}&format=json&username={1}",
            apiKey, username);

    client.DownloadStringAsync(new Uri(URL));
}

Notice, however, that this method doesn’t return information about a user but rather just a NSID – the unique user identifier used by Flickr.

flickr.people.getInfo

This is the method that can give you the user information about a specific Flickr member. As you got the NSID via findByEmail or findByUsername, you can use that NSID to get the details available as public information for the specified user.

public static void GetInfo(string apiKey, string nsid, HelperDelegate helperDelegate)
{
    helperDelegateInstance = helperDelegate;

    WebClient client = new WebClient();
    client.DownloadStringCompleted += new DownloadStringCompletedEventHandler(client_DownloadStringCompleted);
    string URL = string.Format("http://www.flickr.com/services/rest/?method=flickr.people.getInfo&api_key={0}&format=json&user_id={1}",
            apiKey, nsid);

    client.DownloadStringAsync(new Uri(URL));
}

The returned result can look similar to this:

jsonFlickrApi({"person":{"id":"47289884@N03", "nsid":"47289884@N03", "ispro":0, "iconserver":"2762", "iconfarm":3, "path_alias":"dennisdel", "username":{"_content":"Dennis K. Delimarsky"}, "realname":{"_content":"Dennis Delimarsky"}, "location":{"_content":""}, "photosurl":{"_content":"http:\/\/www.flickr.com\/photos\/dennisdel\/"}, "profileurl":{"_content":"http:\/\/www.flickr.com\/people\/dennisdel\/"}, "mobileurl":{"_content":"http:\/\/m.flickr.com\/photostream.gne?id=47266830"}, "photos":{"firstdatetaken":{"_content":"2008-08-23 03:16:21"}, "firstdate":{"_content":"1265544318"}, "count":{"_content":80}}}, "stat":"ok"})

It gives you enough information to access the user’s photostream and see some information about user content submitted to Flickr.

flickr.people.getPhotos

This is the method you should use to retrieve the list of photos belonging to a certain user. This method does require authentication, so you will have to pass your auth token as well as a signature based on the passed parameters and application secret identifier.

The implementation of this method looks a bit more complicated (mind you, it only looks complicated) because there are more parameters involved and passing them to the URL is performed with the help of a few enums.

static void GetPhotos (string apiKey, string authToken, string signature, string nsid, HelperDelegate helperDelegate,
    SafeSearch safeSearch = SafeSearch.Undefined, string minUploadDate = "", string maxUploadDate="", string minTakenDate = "",
    string maxTakenDate = "", ContentType contentType = ContentType.Undefined, PrivacyFilter privacyFilter = PrivacyFilter.Undefined,
    string[] extras = null, string perPage = "",string page="")
{
    helperDelegateInstance = helperDelegate;

    WebClient client = new WebClient();
    client.DownloadStringCompleted += new DownloadStringCompletedEventHandler(client_DownloadStringCompleted);
    string URL = string.Format("http://www.flickr.com/services/rest/?method=flickr.people.getPhotos&api_key={0}&format=json&user_id={1}&api_sig={2}&auth_token={3}",
            apiKey, nsid,signature,authToken);

    if (safeSearch != SafeSearch.Undefined)
    {
        URL += "&safe_search=" + ((int)safeSearch).ToString();
    }

    if (contentType != ContentType.Undefined)
    {
        URL += "&content_type=" + ((int)contentType).ToString();
    }

    if (privacyFilter != PrivacyFilter.Undefined)
    {
        URL += "&privacy_filter=" + ((int)privacyFilter).ToString();
    }

    if (minUploadDate != "")
    {
        URL += "&min_upload_date=" + minUploadDate;
    }

    if (maxUploadDate != "")
    {
        URL += "&max_upload_date=" + maxUploadDate;
    }

    if (minTakenDate != "")
    {
        URL += "&min_taken_date=" + minTakenDate;
    }

    if (maxTakenDate != "")
    {
        URL += "&max_upload_date=" + maxTakenDate;
    }

    if (extras != null)
    {
        string toAdd = "&extras=";
        for (int i = 0; i < extras.Length; i++)
        {
            if (i != extras.Length - 1)
                toAdd += extras[i] + ",";
            else
                toAdd += extras[i];
        }
        URL += toAdd;
    }

    if (page != "")
    {
        URL += "&page=" + page;
    }

    if (perPage != "")
    {
        URL += "&per_page=" + perPage;
    }

    client.DownloadStringAsync(new Uri(URL));
}

The linked enums are the following:

public enum SafeSearch
{
    Undefined = 0,
    Safe =1,
    Moderate = 2,
    Restricted = 3
}

public enum ContentType
{
    Undefined =0,
    Photos = 1,
    Screenshots = 2,
    Other = 3,
    PhotosAndScreenshots = 4,
    ScreenshotsAndOther = 5,
    PhotosAndOther = 6,
    All = 7
}

public enum PrivacyFilter
{
    Undefined = 0,
    Public = 1,
    PrivateVisibleToFriends = 2,
    PrivateVisibleToFamily = 3,
    PrivateVisibleToBoth = 4,
    CompletelyPrivate = 5
}

flickr.people.getPhotosOf

Via this method, you can get the list of photos portraying a specific member. Basically, it returns the list of photos where a Flickr member was tagged.

This method does not require authentication and it only requires an API key and the member NSID. However, you can specify additional information to be displayed that is related to each photo that is found via this call.

public static void GetPhotosOf(string apiKey, string nsid, HelperDelegate helperDelegate, string[] extras = null, string page ="", string perPage = "")
{
    helperDelegateInstance = helperDelegate;

    WebClient client = new WebClient();
    client.DownloadStringCompleted += new DownloadStringCompletedEventHandler(client_DownloadStringCompleted);
    string URL = string.Format("http://www.flickr.com/services/rest/?method=flickr.people.getPhotosOf&api_key={0}&format=json&user_id={1}",
            apiKey, nsid);
    
    if (extras != null)
    {
        string toAdd = "&extras=";
        for (int i = 0; i < extras.Length; i++)
        {
            if (i != extras.Length - 1)
                toAdd += extras[i] + ",";
            else
                toAdd += extras[i];
        }
        URL += toAdd;
    }

    if (page != "")
    {
        URL += "&page=" + page;
    }

    if (perPage != "")
    {
        URL += "&per_page=" + perPage;
    }
    client.DownloadStringAsync(new Uri(URL));
}

flickr.people.getPublicGroups

This method returns all groups where the member with the passed NSID is a member, including those that are 18+. As a part of the response, you will see whether the member is an admin in the specified group or not.

public static void GetPublicGroups(string apiKey, string nsid, HelperDelegate helperDelegate)
{
    helperDelegateInstance = helperDelegate;

    WebClient client = new WebClient();
    client.DownloadStringCompleted += new DownloadStringCompletedEventHandler(client_DownloadStringCompleted);
    string URL = string.Format("http://www.flickr.com/services/rest/?method=flickr.people.getPublicGroups&api_key={0}&format=json&user_id={1}",
            apiKey, nsid);

    client.DownloadStringAsync(new Uri(URL));
}

flickr.people.getPublicGroups

Unlike getPhotos, this method will return only the photos that are set as public. This is a good way to test your account to see what others can view directly out of your photostream – that way you can easily adjust permissions for specific photos.

This method does not require authentication, but you will still have to pass the API key.

When you are calling this method, you can specify a SafeSearch value – that way only photos that are safe for a specific environment can be displayed. For this purpose, I am able to reuse the already existing SafeSearch enum.

static void GetPublicPhotos(string apiKey, string authToken, string signature, string nsid, HelperDelegate helperDelegate,
        SafeSearch safeSearch = SafeSearch.Undefined, string[] extras = null, string perPage = "", string page = "")
{
    helperDelegateInstance = helperDelegate;

    WebClient client = new WebClient();
    client.DownloadStringCompleted += new DownloadStringCompletedEventHandler(client_DownloadStringCompleted);
    string URL = string.Format("http://www.flickr.com/services/rest/?method=flickr.people.getPhotos&api_key={0}&format=json&user_id={1}&api_sig={2}&auth_token={3}",
            apiKey, nsid, signature, authToken);

    if (safeSearch != SafeSearch.Undefined)
    {
        URL += "&safe_search=" + ((int)safeSearch).ToString();
    }

    if (extras != null)
    {
        string toAdd = "&extras=";
        for (int i = 0; i < extras.Length; i++)
        {
            if (i != extras.Length - 1)
                toAdd += extras[i] + ",";
            else
                toAdd += extras[i];
        }
        URL += toAdd;
    }

    if (page != "")
    {
        URL += "&page=" + page;
    }

    if (perPage != "")
    {
        URL += "&per_page=" + perPage;
    }

    client.DownloadStringAsync(new Uri(URL));
}

Notice, that you cannot specify additional search criteria for photos you are retrieving. If you need to search based on specific parameters (e.g. maximum date taken), you should use getPhotos instead, but that will require authentication.

flickr.people.getUploadStatus

getUploadStatus provides some information regarding general Flickr usage statistics applied to the calling user. You cannot query other users with the help of this API call. Although this method does not require additional parameters, it requires authentication – therefore, you need to make sure that you pass a correct auth token and signature in addition to the API key.

public static void GetUploadStatus(string apiKey, string authToken, string signature, HelperDelegate helperDelegate)
{
    helperDelegateInstance = helperDelegate;

    WebClient client = new WebClient();
    client.DownloadStringCompleted += new DownloadStringCompletedEventHandler(client_DownloadStringCompleted);
    string URL = string.Format("http://www.flickr.com/services/rest/?method=flickr.people.getUploadStatus&api_key={0}&format=json&auth_token={1}&api_sig={2}",
            apiKey, authToken,signature);

    client.DownloadStringAsync(new Uri(URL));
}

If I call this method signing with it with my credentials, the output is this:

jsonFlickrApi({"user":{"id":"47289884@N03", "ispro":0, "username":{"_content":"Dennis K. Delimarsky"}, "bandwidth":{"max":104857600, "used":395264, "maxbytes":104857600, "usedbytes":"395264", "remainingbytes":"104462336", "maxkb":102400, "usedkb":386, "remainingkb":102014, "unlimited":0}, "filesize":{"max":10485760, "maxbytes":10485760, "maxkb":10240, "maxmb":10}, "sets":{"created":null, "remaining":"lots"}, "videosize":{"maxbytes":157286400, "maxkb":153600, "maxmb":150}, "videos":{"uploaded":0, "remaining":2}}, "stat":"ok"})

As you can see, there is the allocated and used bandwidth, the number of sets created and remaining as well as the same information regarding the videos. According to the API documentation, you shouldn’t be confused by “lots” as the value for the number of remaining sets – it will constantly be like this unless there will be modifications introduced in the Flickr API.

You can download the People class here.