flickrex

{
  "stat": "ok",
  "method": {
    "requiredperms": 0,
    "needssigning": 0,
    "needslogin": 0,
    "name": "flickr.photos.search",
    "explanation": {
      "_content": "Please note that Flickr will return at most the first 4,000 results for any given search query.  If this is an issue, we recommend trying a more specific query."
    },
    "description": {
      "_content": "Return a list of photos matching some criteria. Only photos visible to the calling user will be returned. To return private or semi-private photos, the caller must be authenticated with 'read' permissions, and have permission to view the photos. Unauthenticated calls will only return public photos."
    }
  },
  "errors": {
    "error": [
      {
        "message": "Too many tags in ALL query",
        "code": "1",
        "_content": "When performing an 'all tags' search, you may not specify more than 20 tags to join together."
      },
      {
        "message": "Unknown user",
        "code": "2",
        "_content": "A user_id was passed which did not match a valid flickr user."
      },
      {
        "message": "Parameterless searches have been disabled",
        "code": "3",
        "_content": "To perform a search with no parameters (to get the latest public photos, please use flickr.photos.getRecent instead)."
      },
      {
        "message": "You don't have permission to view this pool",
        "code": "4",
        "_content": "The logged in user (if any) does not have permission to view the pool for this group."
      },
      {
        "message": "User deleted",
        "code": "5",
        "_content": "The user id passed did not match a Flickr user."
      },
      {
        "message": "Sorry, the Flickr search API is not currently available.",
        "code": "10",
        "_content": "The Flickr API search databases are temporarily unavailable."
      },
      {
        "message": "No valid machine tags",
        "code": "11",
        "_content": "The query styntax for the machine_tags argument did not validate."
      },
      {
        "message": "Exceeded maximum allowable machine tags",
        "code": "12",
        "_content": "The maximum number of machine tags in a single query was exceeded."
      },
      {
        "message": "jump_to not avaiable for this query",
        "code": "13",
        "_content": "jump_to only supported for some query types."
      },
      {
        "message": "Bad value for jump_to",
        "code": "14",
        "_content": "jump_to must be valid photo ID."
      },
      {
        "message": "Photo not found",
        "code": "15",
        "_content": ""
      },
      {
        "message": "You can only search within your own favorites",
        "code": "16",
        "_content": ""
      },
      {
        "message": "You can only search within your own contacts",
        "code": "17",
        "_content": "The call tried to use the contacts parameter with no user ID or a user ID other than that of the authenticated user."
      },
      {
        "message": "Illogical arguments",
        "code": "18",
        "_content": "The request contained contradictory arguments."
      },
      {
        "message": "Similarity search invalid.",
        "code": "19",
        "_content": "The similarity_id param contains an invalid photo id or the viewer does not have permission to view the photo."
      },
      {
        "message": "Excessive photo offset in search",
        "code": "20",
        "_content": "The search requested photos beyond an allowable offset. Reduce the page number or number of results per page for this search."
      },
      {
        "message": "Invalid API Key",
        "code": 100,
        "_content": "The API key passed was not valid or has expired."
      },
      {
        "message": "Service currently unavailable",
        "code": 105,
        "_content": "The requested service is temporarily unavailable."
      },
      {
        "message": "Write operation failed",
        "code": 106,
        "_content": "The requested operation failed due to a temporary issue."
      },
      {
        "message": "Format \"xxx\" not found",
        "code": 111,
        "_content": "The requested response format was not found."
      },
      {
        "message": "Method \"xxx\" not found",
        "code": 112,
        "_content": "The requested method was not found."
      },
      {
        "message": "Invalid SOAP envelope",
        "code": 114,
        "_content": "The SOAP envelope send in the request could not be parsed."
      },
      {
        "message": "Invalid XML-RPC Method Call",
        "code": 115,
        "_content": "The XML-RPC request document could not be parsed."
      },
      {
        "message": "Bad URL found",
        "code": 116,
        "_content": "One or more arguments contained a URL that has been used for abuse on Flickr."
      }
    ]
  },
  "arguments": {
    "argument": [
      {
        "optional": 0,
        "name": "api_key",
        "_content": "Your API application key. <a href=\"/services/api/misc.api_keys.html\">See here</a> for more details."
      },
      {
        "optional": "1",
        "name": "user_id",
        "_content": "The NSID of the user who's photo to search. If this parameter isn't passed then everybody's public photos will be searched. A value of \"me\" will search against the calling user's photos for authenticated calls."
      },
      {
        "optional": "1",
        "name": "tags",
        "_content": "A comma-delimited list of tags. Photos with one or more of the tags listed will be returned. You can exclude results that match a term by prepending it with a - character."
      },
      {
        "optional": "1",
        "name": "tag_mode",
        "_content": "Either 'any' for an OR combination of tags, or 'all' for an AND combination. Defaults to 'any' if not specified."
      },
      {
        "optional": "1",
        "name": "text",
        "_content": "A free text search. Photos who's title, description or tags contain the text will be returned. You can exclude results that match a term by prepending it with a - character."
      },
      {
        "optional": "1",
        "name": "min_upload_date",
        "_content": "Minimum upload date. Photos with an upload date greater than or equal to this value will be returned. The date can be in the form of a unix timestamp or mysql datetime."
      },
      {
        "optional": "1",
        "name": "max_upload_date",
        "_content": "Maximum upload date. Photos with an upload date less than or equal to this value will be returned. The date can be in the form of a unix timestamp or mysql datetime."
      },
      {
        "optional": "1",
        "name": "min_taken_date",
        "_content": "Minimum taken date. Photos with an taken date greater than or equal to this value will be returned. The date can be in the form of a mysql datetime or unix timestamp."
      },
      {
        "optional": "1",
        "name": "max_taken_date",
        "_content": "Maximum taken date. Photos with an taken date less than or equal to this value will be returned. The date can be in the form of a mysql datetime or unix timestamp."
      },
      {
        "optional": "1",
        "name": "license",
        "_content": "The license id for photos (for possible values see the flickr.photos.licenses.getInfo method). Multiple licenses may be comma-separated."
      },
      {
        "optional": "1",
        "name": "sort",
        "_content": "The order in which to sort returned photos. Deafults to date-posted-desc (unless you are doing a radial geo query, in which case the default sorting is by ascending distance from the point specified). The possible values are: date-posted-asc, date-posted-desc, date-taken-asc, date-taken-desc, interestingness-desc, interestingness-asc, and relevance."
      },
      {
        "optional": "1",
        "name": "privacy_filter",
        "_content": "Return photos only matching a certain privacy level. This only applies when making an authenticated call to view photos you own. Valid values are:\n<ul>\n<li>1 public photos</li>\n<li>2 private photos visible to friends</li>\n<li>3 private photos visible to family</li>\n<li>4 private photos visible to friends & family</li>\n<li>5 completely private photos</li>\n</ul>\n"
      },
      {
        "optional": "1",
        "name": "bbox",
        "_content": "A comma-delimited list of 4 values defining the Bounding Box of the area that will be searched.\n<br /><br />\nThe 4 values represent the bottom-left corner of the box and the top-right corner, minimum_longitude, minimum_latitude, maximum_longitude, maximum_latitude.\n<br /><br />\nLongitude has a range of -180 to 180 , latitude of -90 to 90. Defaults to -180, -90, 180, 90 if not specified.\n<br /><br />\nUnlike standard photo queries, geo (or bounding box) queries will only return 250 results per page.\n<br /><br />\nGeo queries require some sort of limiting agent in order to prevent the database from crying. This is basically like the check against \"parameterless searches\" for queries without a geo component.\n<br /><br />\nA tag, for instance, is considered a limiting agent as are user defined min_date_taken and min_date_upload parameters &#8212; If no limiting factor is passed we return only photos added in the last 12 hours (though we may extend the limit in the future)."
      },
      {
        "optional": "1",
        "name": "accuracy",
        "_content": "Recorded accuracy level of the location information.  Current range is 1-16 : \n\n<ul>\n<li>World level is 1</li>\n<li>Country is ~3</li>\n<li>Region is ~6</li>\n<li>City is ~11</li>\n<li>Street is ~16</li>\n</ul>\n\nDefaults to maximum value if not specified."
      },
      {
        "optional": "1",
        "name": "safe_search",
        "_content": "Safe search setting:\n\n<ul>\n<li>1 for safe.</li>\n<li>2 for moderate.</li>\n<li>3 for restricted.</li>\n</ul>\n\n(Please note: Un-authed calls can only see Safe content.)"
      },
      {
        "optional": "1",
        "name": "content_type",
        "_content": "Content Type setting:\n<ul>\n<li>1 for photos only.</li>\n<li>2 for screenshots only.</li>\n<li>3 for 'other' only.</li>\n<li>4 for photos and screenshots.</li>\n<li>5 for screenshots and 'other'.</li>\n<li>6 for photos and 'other'.</li>\n<li>7 for photos, screenshots, and 'other' (all).</li>\n</ul>"
      },
      {
        "optional": "1",
        "name": "machine_tags",
        "_content": "Aside from passing in a fully formed machine tag, there is a special syntax for searching on specific properties :\n\n<ul>\n  <li>Find photos using the 'dc' namespace :    <code>\"machine_tags\" => \"dc:\"</code></li>\n\n  <li> Find photos with a title in the 'dc' namespace : <code>\"machine_tags\" => \"dc:title=\"</code></li>\n\n  <li>Find photos titled \"mr. camera\" in the 'dc' namespace : <code>\"machine_tags\" => \"dc:title=\\\"mr. camera\\\"</code></li>\n\n  <li>Find photos whose value is \"mr. camera\" : <code>\"machine_tags\" => \"*:*=\\\"mr. camera\\\"\"</code></li>\n\n  <li>Find photos that have a title, in any namespace : <code>\"machine_tags\" => \"*:title=\"</code></li>\n\n  <li>Find photos that have a title, in any namespace, whose value is \"mr. camera\" : <code>\"machine_tags\" => \"*:title=\\\"mr. camera\\\"\"</code></li>\n\n  <li>Find photos, in the 'dc' namespace whose value is \"mr. camera\" : <code>\"machine_tags\" => \"dc:*=\\\"mr. camera\\\"\"</code></li>\n\n </ul>\n\nMultiple 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\nto (8)."
      },
      {
        "optional": "1",
        "name": "machine_tag_mode",
        "_content": "Either 'any' for an OR combination of tags, or 'all' for an AND combination. Defaults to 'any' if not specified."
      },
      {
        "optional": "1",
        "name": "group_id",
        "_content": "The id of a group who's pool to search.  If specified, only matching photos posted to the group's pool will be returned."
      },
      {
        "optional": "1",
        "name": "contacts",
        "_content": "Search your contacts. Either 'all' or 'ff' for just friends and family. (Experimental)"
      },
      {
        "optional": "1",
        "name": "woe_id",
        "_content": "A 32-bit identifier that uniquely represents spatial entities. (not used if bbox argument is present). \n<br /><br />\nGeo queries require some sort of limiting agent in order to prevent the database from crying. This is basically like the check against \"parameterless searches\" for queries without a geo component.\n<br /><br />\nA tag, for instance, is considered a limiting agent as are user defined min_date_taken and min_date_upload parameters &mdash; If no limiting factor is passed we return only photos added in the last 12 hours (though we may extend the limit in the future)."
      },
      {
        "optional": "1",
        "name": "place_id",
        "_content": "A Flickr place id.  (not used if bbox argument is present).\n<br /><br />\nGeo queries require some sort of limiting agent in order to prevent the database from crying. This is basically like the check against \"parameterless searches\" for queries without a geo component.\n<br /><br />\nA tag, for instance, is considered a limiting agent as are user defined min_date_taken and min_date_upload parameters &mdash; If no limiting factor is passed we return only photos added in the last 12 hours (though we may extend the limit in the future)."
      },
      {
        "optional": "1",
        "name": "media",
        "_content": "Filter results by media type. Possible values are <code>all</code> (default), <code>photos</code> or <code>videos</code>"
      },
      {
        "optional": "1",
        "name": "has_geo",
        "_content": "Any photo that has been geotagged, or if the value is \"0\" any photo that has <i>not</i> been geotagged.\n<br /><br />\nGeo queries require some sort of limiting agent in order to prevent the database from crying. This is basically like the check against \"parameterless searches\" for queries without a geo component.\n<br /><br />\nA tag, for instance, is considered a limiting agent as are user defined min_date_taken and min_date_upload parameters &mdash; If no limiting factor is passed we return only photos added in the last 12 hours (though we may extend the limit in the future)."
      },
      {
        "optional": "1",
        "name": "geo_context",
        "_content": "Geo context is a numeric value representing the photo's geotagginess beyond latitude and longitude. For example, you may wish to search for photos that were taken \"indoors\" or \"outdoors\". <br /><br />\nThe current list of context IDs is :<br /><br/>\n<ul>\n<li><strong>0</strong>, not defined.</li>\n<li><strong>1</strong>, indoors.</li>\n<li><strong>2</strong>, outdoors.</li>\n</ul>\n<br /><br />\nGeo queries require some sort of limiting agent in order to prevent the database from crying. This is basically like the check against \"parameterless searches\" for queries without a geo component.\n<br /><br />\nA tag, for instance, is considered a limiting agent as are user defined min_date_taken and min_date_upload parameters &mdash; If no limiting factor is passed we return only photos added in the last 12 hours (though we may extend the limit in the future)."
      },
      {
        "optional": "1",
        "name": "lat",
        "_content": "A valid latitude, in decimal format, for doing radial geo queries.\n<br /><br />\nGeo queries require some sort of limiting agent in order to prevent the database from crying. This is basically like the check against \"parameterless searches\" for queries without a geo component.\n<br /><br />\nA tag, for instance, is considered a limiting agent as are user defined min_date_taken and min_date_upload parameters &mdash; If no limiting factor is passed we return only photos added in the last 12 hours (though we may extend the limit in the future)."
      },
      {
        "optional": "1",
        "name": "lon",
        "_content": "A valid longitude, in decimal format, for doing radial geo queries.\n<br /><br />\nGeo queries require some sort of limiting agent in order to prevent the database from crying. This is basically like the check against \"parameterless searches\" for queries without a geo component.\n<br /><br />\nA tag, for instance, is considered a limiting agent as are user defined min_date_taken and min_date_upload parameters &mdash; If no limiting factor is passed we return only photos added in the last 12 hours (though we may extend the limit in the future)."
      },
      {
        "optional": "1",
        "name": "radius",
        "_content": "A valid radius used for geo queries, greater than zero and less than 20 miles (or 32 kilometers), for use with point-based geo queries. The default value is 5 (km)."
      },
      {
        "optional": "1",
        "name": "radius_units",
        "_content": "The unit of measure when doing radial geo queries. Valid options are \"mi\" (miles) and \"km\" (kilometers). The default is \"km\"."
      },
      {
        "optional": "1",
        "name": "is_commons",
        "_content": "Limit the scope of the search to only photos that are part of the <a href=\"http://flickr.com/commons\">Flickr Commons project</a>. Default is false."
      },
      {
        "optional": "1",
        "name": "in_gallery",
        "_content": "Limit the scope of the search to only photos that are in a <a href=\"http://www.flickr.com/help/galleries/\">gallery</a>?  Default is false, search all photos."
      },
      {
        "optional": "1",
        "name": "is_getty",
        "_content": "Limit the scope of the search to only photos that are for sale on Getty. Default is false."
      },
      {
        "optional": 1,
        "name": "extras",
        "_content": "A comma-delimited list of extra information to fetch for each returned record. Currently supported fields are: <code>description</code>, <code>license</code>, <code>date_upload</code>, <code>date_taken</code>, <code>owner_name</code>, <code>icon_server</code>, <code>original_format</code>, <code>last_update</code>, <code>geo</code>, <code>tags</code>, <code>machine_tags</code>, <code>o_dims</code>, <code>views</code>, <code>media</code>, <code>path_alias</code>, <code>url_sq</code>, <code>url_t</code>, <code>url_s</code>, <code>url_q</code>, <code>url_m</code>, <code>url_n</code>, <code>url_z</code>, <code>url_c</code>, <code>url_l</code>, <code>url_o</code>"
      },
      {
        "optional": 1,
        "name": "per_page",
        "_content": "Number of photos to return per page. If this argument is omitted, it defaults to 100. The maximum allowed value is 500."
      },
      {
        "optional": 1,
        "name": "page",
        "_content": "The page of results to return. If this argument is omitted, it defaults to 1."
      }
    ]
  }
}