doc.search

← All the API methods

Live testing

Search for documents.
Fulltext results are limited to 3 000 documents.

  • This method call does not require authentication.
  • "read" permission is necessary to access to private docs.

URL

http://api.ipernity.com/api/doc.search

Parameters

api_key ∗ Your api_key.
user_id Return documents belonging to this user_id. If ommited the search will be performed in everyone public docs.
media Specify the type of returned documents. media values are : photo, audio, video, other.
share Return the calling user documents matching this privacy level. Values are :
  • 0: private docs
  • 1: docs visible to family
  • 2: docs visible to friends
  • 3: docs visible to friends & family
  • 4: public docs
This parameter will be discarded if the specified user_id is not the calling user.
text Search document titles, descriptions and tags using a fulltext query. (Use +/- for boolean mode)
tags Search document tags using a comma separated list of tags. (a maximum of 20 tags is allowed)
album_id Perform the search in this album ID only.
group_id Perform the search in this group ID only.
license Return documents matching this license or a comma separated list of licenses (ex: 1,3,7). See doc.setLicense for more details about license IDs.
posted_min Specify a minimum posted GMT+0 timestamp.
posted_max Specify a maximum posted GMT+0 timestamp.
created_min Specify a minimum creation date (using the YYYY-MM-DD HH:MM:SS format).
created_max Specify a maximum creation date (using the YYYY-MM-DD HH:MM:SS format).
lat Center point latitude in degrees.
lng Center point longitude in degrees.
dist Radius search size in meters (5 km by default, maximum 30 km).
sort The order in which to sort returned documents. The possible sorts are : relevance, popular, posted-desc, posted-asc, ''created-desc' and 'created-asc'. The default order is relevance.
extra A comma seprarated list of extra information. Extra parameters are: owner, dates, count, license, medias, geo, original.
thumbsize Choose your prefered size for the thumbnails: 75x, 100, 240, 250x, 500, 560, 640, 800, 1024, 1600 or 2048. (Value is 75x by default)
per_page The number of docs to return on each page. (Default is 20, maximum is 100)
page The page of results to return.
∗ : this parameter is required.
You may not combine all search parameters. For example you may not combine group_id and album_id, or a fulltext search with a tag search.
  • Searching text and tags syntax :
  • blue sky clouds : return documents containing any of these words. Rank first the documents containing the 3 words.
  • +blue +sky clouds : return documents showing a "blue sky" with some possible "clouds".
  • +blue +sky -clouds : return documents showing a "blue sky" without any "clouds".
  • "the earth is round, like an orange" : search the exact phrase.
  • The search is case-insensitive but accent-sensitive.
  • Adding a "+", "-" or quotes will activate the boolean search mode.
  • Access to thumbnail size greater than 800 pixels depends on user preferences.

Response

<docs page="1" total="51258" pages="2563" per_page="20">
  <doc doc_id="394926" title="A nice car" license="3">
    <owner user_id="295"/>
    <thumb label="75x" ext="jpg" w="75" h="75" url="http://u1.ipernity.com/2/49/26/394926.e831d113.75x.jpg"/>
    <dates ... if option/>
    <original ... if option and available/>
  </doc>
</docs>

Error codes

1 Search parameter is missing At least one of the text or tags or user_id or album_id or group_id parameter is required.
2 User not found The user ID is either invalid or the account is closed/suspended.
3 Album not found The album ID is invalid or insufficient permissions to view this album.
4 Group not found The group ID is invalid or insufficient permissions to view this group.
100 API Key is missing Please add the api_key parameter to this request.
101 API Key is invalid This API key is invalid or disabled.
102 Invalid format The requested format is invalid. Valid formats are : json, xml, php.
103 Method not found The requested method is invalid or missing.
104 Signature missing The query signature is missing.
105 Signature is invalid The query signature is invalid.
106 Token missing User is not logged. The authentication token is missing.
107 Token invalid The authentication token is invalid.
108 Account closed The user account is closed or suspended.
109 Action blocked This action is blocked because of a member or a group blocklist restriction
110 Insufficient permissions Insufficient permissions for this method.
111 IP not allowed The request came from a remote address not allowed by this application.
112 Application Quota Error The application has reached its requests quota.
113 Client IP Quota Error The client IP has reached a limit. Limits are based on requests per seconds, minutes, hours, ...
120 HTTP POST required This API method must be called using HTTP POST.
121 Invalid SOAP envelope The SOAP envelope could not be parsed.
122 Invalid XML-RPC envelope The XML-RPC envelope could not be parsed.
130 OAuth protocol version unsupported We only support OAuth version 1.1 and 1.1a
131 OAuth parameters are missing Some of the OAuth parameters were not sent: %s%
132 OAuth Clock skew The timestamp sent is out of ranges. Please check your computer clock is not skewed.
133 OAuth Nonce is invalid The OAuth Nonce parameter cannot be used twice.
134 OAuth Timestamp is invalid The OAuth Timestamp parameter is out of ranges (clock skew) or inferior to the previous timestamp sent.
135 OAuth Signature method unsupported The OAuth Signature must be either MD5, HMAC_SHA1 or PLAINTEXT over HTTPS.
500 Service error Service general error.
501 Maintenance mode Service under temporarily maintenance. Thank you for your kind understanding.
503 Service unavailable The service is temporarily unavailable. Please try again in a few minutes.

Changelog

  • 2008-12-01: Method created.
  • 2009-01-10: Added a sort parameter.
  • 2009-05-25: Error codes have changed.
  • 2010-09-02: Added safety.

See also