Advanced SearchWeb Services XML-RPC API
iStockphoto provides web services via an XML-RPC API. See http://www.xmlrpc.com/spec for a basic introduction to the XML-RPC web standard.
The XML-RPC web service provides access to a wide range of iStockphoto.com functionality and content including:
- full search capabilities
- lightbox management
- file downloading
- member statistics
- contributor portfolio management
- image uploading
Login, or contact Support for more information on gaining access to the API methods and documentation.
More information can also be found in the XML-RPC webservices API forum.
Header
POST /webservices/xmlrpc/?sessionID=000012002002301230120320660 HTTP/1.0
User-Agent: [Requesting Application] ([operating system])
Host: www.istockphoto.com
Content-Type: text/xml
Content-length: [bytes]
Body
<?xml version="1.0" encoding="utf-8"?>
<methodCall>
<methodName>istockphoto.test.test</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>name</name>
<value><string>value</string></value>
</member>
<member>
<name>name2</name>
<value><string>value2</string></value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>
Success
<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
<params>
<param>
<value>
<string>
[escaped-xml-payload]
</string>
</value>
</param>
</params>
</methodResponse>
Error
<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value><int>[error-code]</int></value>
</member>
<member>
<name>faultString</name>
<value><string>[error-message]</string></value>
</member>
</struct>
</value>
</fault>
</methodResponse>
XML Payload
The string value in every response is a block of escaped XML. To use the response value a developer simply needs to un-escape and parse the XML block. Every un-escaped XML block will contain a <istockphotoResponse> tag, and all response information will be contained within that tag. The <istockphotoResponse> tag will include a sessionID parameter that can be re-used in the next request. An example of an un-escaped XML payload is:
<istockphotoResponse sessionid="000123401200002312">
[xml data pertinent to the request]
</istockphotoResponse>
The following standards are used for variable, method and element names:
| Element | Example | Description |
|---|---|---|
| XML-RPC method names | istockphoto.image.getInfo | dot separated list of mixed case strings (the first character of each mixed-case string is always lowercase), representing the domain, the class, and the name of the method. |
| XML-RPC parameter names | fileID | mixed-case (all characters in an acronym use the case of the first character in the acronym) |
| XML tag names | imageList | mixed-case |
| XML tag property names | filename | lower-case |
Most of the functionality offered through the API requires iStockphoto member authentication. There are three authentication options. apiKey holders should refer to their API Terms of use for more information on which authentication options they may use (not all aptions are available to all apiKey holders).
-
Send loginMembername and loginPassword parameters with the XML-RPC method call.
This approach is discouraged because there is no encryption on the transfer of the password.
-
Use istockphoto.auth.login
An authenticated sessionID can be requested over a secure connection using this method. The provided sessionID should be included in subsequent HTTP requests.
Parameter Type Required Default Description loginMembername string yes the member name of the iStockphoto member loginPassword string yes the password of the iStockphoto member This approach is prefered for desktop applications.
-
Use istockphoto.auth.loginWithToken
An authenticated sessionID can be requested over a secure connection using this method. The provided sessionID should be included in subsequent HTTP requests.
Parameter Type Required Default Description loginToken string yes the login token ID. See the istockphoto.getLoginTokenURL method for details on generating a login token. This approach is prefered for web applications. See an example here
Certain methods that do not require authentication are session-based (e.g., istockphoto.search.browseCache) and so require a valid sessionID to be included in the HTTP request URL. In such cases, the developer can use the sessionID value returned in the previous XML-RPC response for the next request without explicitly calling the istockphoto.auth.login or istockphoto.auth.loginWithToken methods. The sessionID can and will change during a session, so the most recently provided value should be used.
Login Flow Diagram
Login Token Flow Diagram
Session Flow Diagram
All requests to the XML-RPC web services require authorization. Developers may gain access to the web services by submitting a request for an apiKey (contact Support for more information). The apiKey must be sent as a parameter with every XML-RPC method call.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| apiKey | string | yes | a unique key required by each developer in order to access any XML-RPC method |
Host Name and Path
All calls will need to be made to http://api.istockphoto.com and methods requiring secure will need to go to https://secure-api.istockphoto.com. The path for all XML-RPC requests is still /webservices/xmlrpc.
Parameters
Requests to methods that require authentication should include a sessionID URL parameter such that the HTTP POST path might look like "/webservices/xmlrpc?sessionID=0000213003400002343240".
Image thumbnails cannot be downloaded directly through the XML-RPC interface. However, constructing a URL to download an image is quite simple:
In this example, file ID is replaced with the ID of the file, and thumbnail size is replaced with an integer: 1 for the small thumbnail, 2 for the large watermarked thumbnail.
ALL REQUESTS TO XML-RPC WEB SERVICES MUST BE ENCODED AS UTF-8.
All Request Parameters must be encoded the same way that the posted data from a WWW form is encoded. That is, all values that should be encoded (i.e. <, >, ) must be replaced with a percent (%) sign followed by two hex digits. See: http://www.lookuptables.com/ for hex values on all characters.
Use of iStockphoto's Web Services is subject to the TERMS OF USE which governs your use of the iStockphoto website. These terms may be amended at any time. Access to the Web Services may be revoked at anytime and without notice at the sole discretion of iStockphoto. Other applicable agreements between the Web Service user and iStockphoto may also exist.