com.aetrion.flickr.places
Class PlacesInterface

java.lang.Object
  extended by com.aetrion.flickr.places.PlacesInterface

public class PlacesInterface
extends java.lang.Object

Lookup Flickr Places.

Announcement on places from yahoo:

From: kellan 
Date: Fri, 11 Jan 2008 15:57:59 -0800
Subject: [yws-flickr] Flickr and "Place IDs"

At Flickr we've got a really big database that lists a significant 
percentage of the places that exist in the world, and a few that don't. 
When you geotag a photo we try to identify the "place" (neighborhood, 
village, city, county, state, or country) where the photo was taken. And 
we assign that photo a "place ID".

A place ID is a globally unique identifier for a place on Earth.  A city 
has a place ID, so do counties, states, and countries.  Even some 
neighborhoods and landmarks have them, though Flickr isn't currently 
tracking those. And we're starting to expose these place IDs around Flickr.

### Place IDs and flickr.photos.search()

The Flickr API method flickr.photos.search() now accepts place_id as an 
argument.  Along with all of the other parameters you can
search on you can now scope your search to a given place.   Historically 
you've been able to pass bounding boxes to the API, but calculating the 
right bounding box for a city is tricky, and you can get noise and bad 
results around the edge.  Now you can pass a single non-ambiguous string 
and get photos geotagged in San Francisco, CA, or Ohio, or Beijing. 
(kH8dLOubBZRvX_YZ, LtkqzVqbApjAbJxv, and wpK7URqbAJnWB90W respectively)

The documentation has been updated at:
http://www.flickr.com/services/api/flickr.photos.search.html

### Sources of Place IDs

Place IDs are now returned from a number of source:
 flickr.photos.getInfo will return place IDs for geotagged photos
 available as a microformat on the appropriate Places page
 flickr.places.resolvePlaceURL, and flickr.places.resolvePlaceId are
available for round tripping Flickr Places URLs.

http://www.flickr.com/services/api/flickr.photos.getInfo.html
http://www.flickr.com/services/api/flickr.places.resolvePlaceURL.html
http://www.flickr.com/services/api/flickr.places.resolvePlaceId.html

### More Place IDs

Right now you can also place IDs in the places URL, and pass them to the 
map like so:

 http://flickr.com/places/wpK7URqbAJnWB90W
 http://flickr.com/map?place_id=kH8dLOubBZRvX_YZ

### Place IDs elsewhere

The especially eagle-eyed among you might recognize Place IDs.  Upcoming 
has been quietly using them for months to uniquely identify their metros.

See events from San Francisco at:
http://upcoming.yahoo.com/place/kH8dLOubBZRvX_YZ

See photos from San Francisco at: http://flickr.com/places/kH8dLOubBZRvX_YZ

Additionally Yahoo's skunkworks project FireEagle will also support 
place IDs.

And yes, there is more work to do, but we're exciting about this as a start.

Thanks,
-kellan

Version:
$Id: PlacesInterface.java,v 1.9 2009/07/03 22:31:40 x-mago Exp $
Author:
mago

Constructor Summary
PlacesInterface(java.lang.String apiKey, java.lang.String sharedSecret, Transport transportAPI)
           
 
Method Summary
 PlacesList find(java.lang.String query)
          Return a list of place IDs for a query string.
 PlacesList findByLatLon(double latitude, double longitude, int accuracy)
          Return a place ID for a latitude, longitude and accuracy triple.
 PlacesList getChildrenWithPhotosPublic(java.lang.String placeId, java.lang.String woeId)
          Return a list of locations with public photos that are parented by a Where on Earth (WOE) or Places ID.
 Location getInfo(java.lang.String placeId, java.lang.String woeId)
          Get informations about a place.
 Location getInfoByUrl(java.lang.String url)
          Lookup information about a place, by its flickr.com/places URL.
 java.util.ArrayList getPlaceTypes()
          Fetches a list of available place types for Flickr.
 java.util.ArrayList getShapeHistory(java.lang.String placeId, java.lang.String woeId)
          Return an historical list of all the shape data generated for a Places or Where on Earth (WOE) ID.
 PlacesList getTopPlacesList(int placeType, java.util.Date date, java.lang.String placeId, java.lang.String woeId)
          Return the top 100 most geotagged places for a day.
 java.lang.String intPlaceTypeToString(int placeType)
           
 PlacesList placesForBoundingBox(int placeType, java.lang.String bbox)
          Return all the locations of a matching place type for a bounding box.
 PlacesList placesForContacts(int placeType, java.lang.String placeId, java.lang.String woeId, java.lang.String threshold, java.lang.String contacts)
          Return a list of the top 100 unique places clustered by a given placetype for a user's contacts.
 PlacesList placesForTags(int placeTypeId, java.lang.String woeId, java.lang.String placeId, java.lang.String threshold, java.lang.String[] tags, java.lang.String tagMode, java.lang.String machineTags, java.lang.String machineTagMode, java.util.Date minUploadDate, java.util.Date maxUploadDate, java.util.Date minTakenDate, java.util.Date maxTakenDate)
          Return a list of the top 100 unique places clustered by a given placetype for set of tags or machine tags.
 PlacesList placesForUser(int placeType, java.lang.String woeId, java.lang.String placeId, java.lang.String threshold, java.util.Date minUploadDate, java.util.Date maxUploadDate, java.util.Date minTakenDate, java.util.Date maxTakenDate)
          Return a list of the top 100 unique places clustered by a given placetype for a user.
 Location resolvePlaceId(java.lang.String placeId)
          Deprecated. This method has been deprecated. It won't be removed but you should use getInfo(String, String) instead.
 Location resolvePlaceURL(java.lang.String flickrPlacesUrl)
          Deprecated. This method has been deprecated. It won't be removed but you should use getInfoByUrl(String) instead.
 java.util.ArrayList tagsForPlace(java.lang.String woeId, java.lang.String placeId, java.util.Date minUploadDate, java.util.Date maxUploadDate, java.util.Date minTakenDate, java.util.Date maxTakenDate)
          Return a list of the top 100 unique tags for a Flickr Places or Where on Earth (WOE) ID.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PlacesInterface

public PlacesInterface(java.lang.String apiKey,
                       java.lang.String sharedSecret,
                       Transport transportAPI)
Method Detail

find

public PlacesList find(java.lang.String query)
                throws FlickrException,
                       java.io.IOException,
                       org.xml.sax.SAXException
Return a list of place IDs for a query string. The flickr.places.find method is not a geocoder. It will round "up" to the nearest place type to which place IDs apply. For example, if you pass it a street level address it will return the city that contains the address rather than the street, or building, itself.

This method does not require authentication.

Parameters:
query -
Returns:
PlacesList
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

findByLatLon

public PlacesList findByLatLon(double latitude,
                               double longitude,
                               int accuracy)
                        throws FlickrException,
                               java.io.IOException,
                               org.xml.sax.SAXException
Return a place ID for a latitude, longitude and accuracy triple.

The flickr.places.findByLatLon method is not meant to be a (reverse) geocoder in the traditional sense. It is designed to allow users to find photos for "places" and will round up to the nearest place type to which corresponding place IDs apply.

For example, if you pass it a street level coordinate it will return the city that contains the point rather than the street, or building, itself.

It will also truncate latitudes and longitudes to three decimal points.

The gory details : This is (most of) the same magic that is performed when you geotag one of your photos on the site itself. We know that at the neighbourhood level this can get messy and not always return the correct location.

At the city level things are much better but there may still be some gotchas floating around. Sometimes it's as simple as a bug and other times it is an issue of two competing ideas of where a place "is".

This comes with the territory and we are eager to identify and wherever possible fix the problems so when you see something that looks wrong please be gentle :-)

(Reports of incorrect places sent to mailing list will not be ignored but it would be better if you could use the forums for that sort of thing.)

Also, as we do on the site if we can not identify a location for a point as a specific accuracy we pop up the stack and try again. For example, if we can't find a city for a given set of coordinates we try instead to locate the state.

As mentioned above, this method is not designed to serve as a general purpose (reverse) geocoder which is partly reflected by the truncated lat/long coordinates.

If you think that three decimal points are the cause of wonky results locating photos for places, we are happy to investigate but until then it should be All Good (tm).

This method does not require authentication.

Parameters:
latitude - The latitude whose valid range is -90 to 90. Anything more than 4 decimal places will be truncated.
longitude - The longitude whose valid range is -180 to 180. Anything more than 4 decimal places will be truncated.
accuracy -
Returns:
A PlacesList
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

getChildrenWithPhotosPublic

public PlacesList getChildrenWithPhotosPublic(java.lang.String placeId,
                                              java.lang.String woeId)
                                       throws FlickrException,
                                              java.io.IOException,
                                              org.xml.sax.SAXException

Return a list of locations with public photos that are parented by a Where on Earth (WOE) or Places ID.

This method does not require authentication.

Parameters:
placeId - A Flickr Places ID. Can be null. (While optional, you must pass either a valid Places ID or a WOE ID.)
woeId - A Where On Earth (WOE) ID. Can be null. (While optional, you must pass either a valid Places ID or a WOE ID.)
Returns:
List of Places
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

getInfo

public Location getInfo(java.lang.String placeId,
                        java.lang.String woeId)
                 throws FlickrException,
                        java.io.IOException,
                        org.xml.sax.SAXException
Get informations about a place.

This method does not require authentication.

Parameters:
placeId - A Flickr Places ID. Optioal, can be null. (While optional, you must pass either a valid Places ID or a WOE ID.)
woeId - A Where On Earth (WOE) ID. Optional, can be null. (While optional, you must pass either a valid Places ID or a WOE ID.)
Returns:
A Location
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

getInfoByUrl

public Location getInfoByUrl(java.lang.String url)
                      throws FlickrException,
                             java.io.IOException,
                             org.xml.sax.SAXException
Lookup information about a place, by its flickr.com/places URL.

This method does not require authentication.

Parameters:
url -
Returns:
A Location
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

getPlaceTypes

public java.util.ArrayList getPlaceTypes()
                                  throws FlickrException,
                                         java.io.IOException,
                                         org.xml.sax.SAXException
Fetches a list of available place types for Flickr.

This method does not require authentication.

Returns:
A list of placetypes
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

getShapeHistory

public java.util.ArrayList getShapeHistory(java.lang.String placeId,
                                           java.lang.String woeId)
                                    throws FlickrException,
                                           java.io.IOException,
                                           org.xml.sax.SAXException
Return an historical list of all the shape data generated for a Places or Where on Earth (WOE) ID.

This method does not require authentication.

Not working. As it was not possible to find any results. Not even the ones, that have been described in the announcement of this feature.

Parameters:
placeId - A Flickr Places ID. Optional, can be null.
woeId - A Where On Earth (WOE) ID. Optional, can be null.
Returns:
A list of shapes
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

getTopPlacesList

public PlacesList getTopPlacesList(int placeType,
                                   java.util.Date date,
                                   java.lang.String placeId,
                                   java.lang.String woeId)
                            throws FlickrException,
                                   java.io.IOException,
                                   org.xml.sax.SAXException
Return the top 100 most geotagged places for a day.

This method does not require authentication.

Parameters:
placeType -
date - Optional, can be null. The default is yesterday.
placeId - A Flickr Places ID. Optional, can be null.
woeId - A Where On Earth (WOE) ID. Optional, can be null.
Returns:
PlacesList
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

placesForBoundingBox

public PlacesList placesForBoundingBox(int placeType,
                                       java.lang.String bbox)
                                throws FlickrException,
                                       java.io.IOException,
                                       org.xml.sax.SAXException
Return all the locations of a matching place type for a bounding box.

The maximum allowable size of a bounding box (the distance between the SW and NE corners) is governed by the place type you are requesting. Allowable sizes are as follows:

This method does not require authentication.

Parameters:
bbox -
placeType -
Returns:
A PlacesList
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

placesForContacts

public PlacesList placesForContacts(int placeType,
                                    java.lang.String placeId,
                                    java.lang.String woeId,
                                    java.lang.String threshold,
                                    java.lang.String contacts)
                             throws FlickrException,
                                    java.io.IOException,
                                    org.xml.sax.SAXException
Return a list of the top 100 unique places clustered by a given placetype for a user's contacts.

Parameters:
placeType - Use Type-constants at Place
placeId - A Flickr Places ID. Optional, can be null.
woeId - A Where On Earth (WOE) ID. Optional, can be null.
threshold - The minimum number of photos that a place type must have to be included. If the number of photos is lowered then the parent place type for that place will be used. Optional, can be null.
contacts - Search your contacts. Either 'all' or 'ff' for just friends and family. (Optional, default is all)
Returns:
A PlacesList
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

placesForTags

public PlacesList placesForTags(int placeTypeId,
                                java.lang.String woeId,
                                java.lang.String placeId,
                                java.lang.String threshold,
                                java.lang.String[] tags,
                                java.lang.String tagMode,
                                java.lang.String machineTags,
                                java.lang.String machineTagMode,
                                java.util.Date minUploadDate,
                                java.util.Date maxUploadDate,
                                java.util.Date minTakenDate,
                                java.util.Date maxTakenDate)
                         throws FlickrException,
                                java.io.IOException,
                                org.xml.sax.SAXException
Return a list of the top 100 unique places clustered by a given placetype for set of tags or machine tags.

This method does not require authentication.

Parameters:
placeTypeId -
woeId - A Where On Earth (WOE) ID. Optional, can be null. (While optional, you must pass either a valid Places ID or a WOE ID.)
placeId - A Flickr Places ID. Optional, can be null. (While optional, you must pass either a valid Places ID or a WOE ID.)
threshold - The minimum number of photos that a place type must have to be included. If the number of photos is lowered then the parent place type for that place will be used. Optional, can be null.
tags - A String-array of Tags. Photos with one or more of the tags listed will be returned. Optional, can be null.
tagMode - Either 'any' for an OR combination of tags, or 'all' for an AND combination. Defaults to 'any' if not specified. Optional, can be null.
machineTags -
machineTagMode - Either 'any' for an OR combination of tags, or 'all' for an AND combination. Defaults to 'any' if not specified. Optional, can be null.
minUploadDate - Optional, can be null.
maxUploadDate - Optional, can be null.
minTakenDate - Optional, can be null.
maxTakenDate - Optional, can be null.
Returns:
A PlacesList
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

placesForUser

public PlacesList placesForUser(int placeType,
                                java.lang.String woeId,
                                java.lang.String placeId,
                                java.lang.String threshold,
                                java.util.Date minUploadDate,
                                java.util.Date maxUploadDate,
                                java.util.Date minTakenDate,
                                java.util.Date maxTakenDate)
                         throws FlickrException,
                                java.io.IOException,
                                org.xml.sax.SAXException
Return a list of the top 100 unique places clustered by a given placetype for a user.

Parameters:
placeType - Use Type-constants at Place
woeId - A Where On Earth (WOE) ID. Optional, can be null.
placeId - A Flickr Places ID. Optional, can be null.
threshold - The minimum number of photos that a place type must have to be included. If the number of photos is lowered then the parent place type for that place will be used. Optional, can be null.
minUploadDate - Optional, can be null.
maxUploadDate - Optional, can be null.
minTakenDate - Optional, can be null.
maxTakenDate - Optional, can be null.
Returns:
A PlacesList
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

resolvePlaceId

public Location resolvePlaceId(java.lang.String placeId)
                        throws FlickrException,
                               java.io.IOException,
                               org.xml.sax.SAXException
Deprecated. This method has been deprecated. It won't be removed but you should use getInfo(String, String) instead.

Find Flickr Places information by Place ID.

Parameters:
placeId -
Returns:
A Location
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

resolvePlaceURL

public Location resolvePlaceURL(java.lang.String flickrPlacesUrl)
                         throws FlickrException,
                                java.io.IOException,
                                org.xml.sax.SAXException
Deprecated. This method has been deprecated. It won't be removed but you should use getInfoByUrl(String) instead.

Find Flickr Places information by Place URL.

This method does not require authentication.

Parameters:
flickrPlacesUrl -
Returns:
A Location
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

tagsForPlace

public java.util.ArrayList tagsForPlace(java.lang.String woeId,
                                        java.lang.String placeId,
                                        java.util.Date minUploadDate,
                                        java.util.Date maxUploadDate,
                                        java.util.Date minTakenDate,
                                        java.util.Date maxTakenDate)
                                 throws FlickrException,
                                        java.io.IOException,
                                        org.xml.sax.SAXException
Return a list of the top 100 unique tags for a Flickr Places or Where on Earth (WOE) ID.

This method does not require authentication.

Parameters:
woeId - A Where On Earth (WOE) ID. Optional, can be null.
placeId - A Flickr Places ID. Optional, can be null.
minUploadDate - Optional, can be null.
maxUploadDate - Optional, can be null.
minTakenDate - Optional, can be null.
maxTakenDate - Optional, can be null.
Returns:
A list of Tags
Throws:
FlickrException
java.io.IOException
org.xml.sax.SAXException

intPlaceTypeToString

public java.lang.String intPlaceTypeToString(int placeType)
                                      throws FlickrException
Throws:
FlickrException


Copyright (C) 2005-2008 Aetrion LLC. All Rights Reserved.