public class PlacesInterface
extends java.lang.Object
Announcement on places from yahoo:
From: kellanDate: 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
| Constructor and Description |
|---|
PlacesInterface(java.lang.String apiKey,
java.lang.String sharedSecret,
Transport transportAPI) |
| Modifier and Type | Method and Description |
|---|---|
PlacesList<Place> |
find(java.lang.String query)
Return a list of place IDs for a query string.
|
PlacesList<Place> |
findByLatLon(double latitude,
double longitude,
int accuracy)
Return a place ID for a latitude, longitude and accuracy triple.
|
PlacesList<Place> |
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<PlaceType> |
getPlaceTypes()
Fetches a list of available place types for Flickr.
|
java.util.ArrayList<org.w3c.dom.Element> |
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<Place> |
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<Place> |
placesForBoundingBox(int placeType,
java.lang.String bbox)
Return all the locations of a matching place type for a bounding box.
|
PlacesList<Place> |
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<Place> |
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<Place> |
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<Tag> |
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.
|
public PlacesInterface(java.lang.String apiKey,
java.lang.String sharedSecret,
Transport transportAPI)
public PlacesList<Place> find(java.lang.String query) throws FlickrException
This method does not require authentication.
query - FlickrExceptionpublic PlacesList<Place> findByLatLon(double latitude, double longitude, int accuracy) throws FlickrException
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.
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 - FlickrExceptionpublic PlacesList<Place> getChildrenWithPhotosPublic(java.lang.String placeId, java.lang.String woeId) throws FlickrException
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.
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.)FlickrExceptionpublic Location getInfo(java.lang.String placeId, java.lang.String woeId) throws FlickrException
This method does not require authentication.
placeId - A Flickr Places ID. Optional, 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.)FlickrExceptionpublic Location getInfoByUrl(java.lang.String url) throws FlickrException
This method does not require authentication.
url - FlickrExceptionpublic java.util.ArrayList<PlaceType> getPlaceTypes() throws FlickrException
This method does not require authentication.
FlickrExceptionpublic java.util.ArrayList<org.w3c.dom.Element> getShapeHistory(java.lang.String placeId,
java.lang.String woeId)
throws FlickrException
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.
placeId - A Flickr Places ID. Optional, can be null.woeId - A Where On Earth (WOE) ID. Optional, can be null.FlickrExceptionpublic PlacesList<Place> getTopPlacesList(int placeType, java.util.Date date, java.lang.String placeId, java.lang.String woeId) throws FlickrException
This method does not require authentication.
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.FlickrExceptionpublic PlacesList<Place> placesForBoundingBox(int placeType, java.lang.String bbox) throws FlickrException
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.
bbox - placeType - FlickrExceptionpublic PlacesList<Place> placesForContacts(int placeType, java.lang.String placeId, java.lang.String woeId, java.lang.String threshold, java.lang.String contacts) throws FlickrException
placeType - Use Type-constants at PlaceplaceId - 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)FlickrExceptionpublic PlacesList<Place> 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
This method does not require authentication.
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.FlickrExceptionpublic PlacesList<Place> 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
placeType - Use Type-constants at PlacewoeId - 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.FlickrException@Deprecated public Location resolvePlaceId(java.lang.String placeId) throws FlickrException
getInfo(String, String) instead.placeId - FlickrException@Deprecated public Location resolvePlaceURL(java.lang.String flickrPlacesUrl) throws FlickrException
getInfoByUrl(String) instead.This method does not require authentication.
flickrPlacesUrl - FlickrExceptionpublic java.util.ArrayList<Tag> 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
This method does not require authentication.
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.FlickrExceptionpublic java.lang.String intPlaceTypeToString(int placeType)
throws FlickrException
FlickrException