| Section 7 |
 |
API |
| 7.1 Getting started
How to use the Stockxpert API The API works entirely through the URL: http://stockxpert.com/api/ You simply pass a number of parameters to this URL with HTTP using either the GET or POST method. Data is returned in a variety of formats, either JSON, serialized PHP, or XML. You will need to use a scripting language, such as Javascript or PHP (there are many others), to parse the results and display it to the user. For example, with JavaScript you can use AJAX to make a call to the Stockxpert API and the parse the returned JSON or XML results. If using JSON, you can pass a callback function, and the JSON result will be passed as an argument to that function. This allows JavaScript access of the API through dynamic <script> elements. To use the JSON callback function, pass the name of the function to the jsoncallback parameter. Searching Photos To search photos, only two parameters are needed. Pass the 'method' parameter with the value 'photos.search' and the 'keywords' parameter with the search term(s). The URL should look like this: http://stockxpert.com/api/?method=photos.search&keywords=dogs. The result displayed is in JSON format (by default). Since raw JASON output is not ideal to display directly, use a scripting language to wrap a UI around the results. You can use the following parameters to search photos on Stockxpert: REQUIRED PARAMETERS method (Required) Use 'photos.search'. keywords (Required) A space- or comma-delimited list of keywords to be used in searching. All results will match all the keywords. OPTIONAL PARAMETERS format (Optional) You can pass either 'json', 'php' (serialized PHP) or 'xml'. Defaults to 'json'. jsoncallback (Optional) If using JSON formatting, this will be the name of the callback function the JSON data will be passed to. If jsoncallback is not used, the data will not be wrapped in a function call. columns (Optional) A space- or comma-delimited list of data columns to be provided in the data. Possible values include 'userid', 'title', 'description', 'date' and 'downloaded' (how many times the photo was downloaded). The ID and URLs to the thumbnail photos will always be returned. type (Optional) A space- or comma-delimited list of file types required, either 'photos', 'graphics', 'vectors' or 'any'. Defaults to 'any'. sortby (Optional) Indicates how to sort the results, either 'date', 'score' (popularity) or 'downloaded' (number of times downloaded). Defaults to 'score'. order (Optional) Indicates in which direction to order the results, either 'asc' (ascending) or 'desc' (descending). Defaults to 'desc'. page (Optional) Indicates which page of results to return. Pages start counting at 1. Defaults to 1. per_page (Optional) Indicates how many photos per page to return. Only a maximum of 500 photos will be returned. Defaults to 20. ref (Optional) Specifies a Stockxpert user name to be used to generate affiliate links in the search results. Defaults to null. RETURNED RESULTS The following parameters are returned by default in all results. page Indicates which page of results was returned. perpage Indicates the number of results returned for this page. total Indicates the number of total matches for the search term entered. photos Name of the array (or root element) that contains the search results. Each array element is an assicoative array that contains the following keys:
id
Objectid of the current photo
url
Url to the image browse page at Stockxpert.com
img_s
Url to the thumbnail image
img_m
Url to the larger preview image (can be used as a rollover popup image) If anything was specified for the "column" parameter, then those keys will also be included. They are: 'userid', 'title', 'description', 'date' and 'downloaded'
userid
Userid of the image contributor
title
The Title of the image
description
The description of the image
date
The date the image was uploaded to Stockxpert
downloaded
How many times the image has been downloaded Example form 1 This simple form implements only the two required parameters. The action in the form tag calls a JavaScript function which initiates an AJAX call. The search input is passed to the API and results are returned back in the default output as JSON. From that point, JavaScript parses the JSON into a nice table structure and is displayed to the user. Note: For FireFox (and other Mozilla type browsers), XMLHttpRequest needs UniversalBrowserRead, otherwise, you will get the infamous "Error: uncaught exception: Permission denied to call method XMLHttpRequest.open." Downloads Simple form (JS + Ajax) Related topics Usage examples |
