flickr.places.placesForTags

Return a list of the top 100 unique places clustered by a given placetype for set of tags or machine tags.

Authentication

This method does not require authentication.

Arguments

api_key (Required)
Your API application key. See here for more details.
place_type_id (Required)
The numeric ID for a specific place type to cluster photos by.

Valid place type IDs are :
  • 22: neighbourhood
  • 7: locality
  • 8: region
  • 12: country
  • 29: continent
woe_id (Optional)
A Where on Earth identifier to use to filter photo clusters. For example all the photos clustered by locality in the United States (WOE ID 23424977).

(While optional, you must pass either a valid Places ID or a WOE ID.)
place_id (Optional)
A Flickr Places identifier to use to filter photo clusters. For example all the photos clustered by locality in the United States (Place ID 4KO02SibApitvSBieQ).

(While optional, you must pass either a valid Places ID or a WOE ID.)
threshold (Optional)
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.

For example if you only have 3 photos taken in the locality of Montreal (WOE ID 3534) but your threshold is set to 5 then those photos will be "rolled up" and included instead with a place record for the region of Quebec (WOE ID 2344924).
tags (Optional)
A comma-delimited list of tags. Photos with one or more of the tags listed will be returned.

(While optional, you must pass either a valid tag or machine_tag
tag_mode (Optional)
Either 'any' for an OR combination of tags, or 'all' for an AND combination. Defaults to 'any' if not specified.
machine_tags (Optional)
Aside from passing in a fully formed machine tag, there is a special syntax for searching on specific properties :
  • Find photos using the 'dc' namespace : "machine_tags" => "dc:"
  • Find photos with a title in the 'dc' namespace : "machine_tags" => "dc:title="
  • Find photos titled "mr. camera" in the 'dc' namespace : "machine_tags" => "dc:title=\"mr. camera\"
  • Find photos whose value is "mr. camera" : "machine_tags" => "*:*=\"mr. camera\""
  • Find photos that have a title, in any namespace : "machine_tags" => "*:title="
  • Find photos that have a title, in any namespace, whose value is "mr. camera" : "machine_tags" => "*:title=\"mr. camera\""
  • Find photos, in the 'dc' namespace whose value is "mr. camera" : "machine_tags" => "dc:*=\"mr. camera\""
Multiple machine tags may be queried by passing a comma-separated list. The number of machine tags you can pass in a single query depends on the tag mode (AND or OR) that you are querying with. "AND" queries are limited to (16) machine tags. "OR" queries are limited to (8).

(While optional, you must pass either a valid tag or machine_tag)
machine_tag_mode (Optional)
Either 'any' for an OR combination of tags, or 'all' for an AND combination. Defaults to 'any' if not specified.
min_upload_date (Optional)
Minimum upload date. Photos with an upload date greater than or equal to this value will be returned. The date should be in the form of a unix timestamp.
max_upload_date (Optional)
Maximum upload date. Photos with an upload date less than or equal to this value will be returned. The date should be in the form of a unix timestamp.
min_taken_date (Optional)
Minimum taken date. Photos with an taken date greater than or equal to this value will be returned. The date should be in the form of a mysql datetime.
max_taken_date (Optional)
Maximum taken date. Photos with an taken date less than or equal to this value will be returned. The date should be in the form of a mysql datetime.

Example Response

<places total="1">
  <place place_id="kH8dLOubBZRvX_YZ" woeid="2487956" latitude="37.779" longitude="-122.420" place_url="/United+States/California/San+Francisco" place_type="locality" photo_count="156">San Francisco, California</place>
</places>

Error Codes

100: Invalid API Key
The API key passed was not valid or has expired.
105: Service currently unavailable
The requested service is temporarily unavailable.
106: Write operation failed
The requested operation failed due to a temporary issue.
111: Format "xxx" not found
The requested response format was not found.
112: Method "xxx" not found
The requested method was not found.
114: Invalid SOAP envelope
The SOAP envelope send in the request could not be parsed.
115: Invalid XML-RPC Method Call
The XML-RPC request document could not be parsed.
116: Bad URL found
One or more arguments contained a URL that has been used for abuse on Flickr.

API Explorer

API Explorer : flickr.places.placesForTags