Web 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

<istockphotoResponse sessionid="000123401200002312">
   [xml data pertinent to the request]
</istockphotoResponse>
    		

1. 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.

2. 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.



3. 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

Host Name

The default host name for requests is www.istockphoto.com. Some methods (such as istockphoto.auth.login) require the use of secure connection and must be sent to secure.istockphoto.com via an SSL encrypted HTTPS connection.

Path

The path for all XML-RPC requests is /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".

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.