posted this on January 09, 2012 12:57 pm
To use our API you sign up for a Bigstock account and fill out the API getting started form. You will be given an account ID which must be included with every request. To explore, you can interact with most of our API right through your browser. All requests are in the following URL structure:
response_code will always contain a standard HTTP response code. The response_code value should be checked first to verify that the request was successfully processed. If the request was successful, the response_code will contain a value of 200.
message will contain a description of any error that may have occurred and will help in troubleshooting interacting with the Bigstock API.
data contains the information you can use to display content to the end user.
Development and Testing
While developing and learning how to interact with the API, the test interface testapi.bigstockphoto.com should be used. All commands and functionality is exactly the same. Purchases can be made and downloads tested, but there will be no charges made against your account. The downloaded image will be a fixed-resolution test image instead of the actual image requested. If you have not funded your account, all requests will default to the test interface automatically.
Secure connections to the Bigstock API are fully supported, simply direct your requests to https://api.bigstockphoto.com and all image thumbnails will be returned using https.
The response to a successful search request is structured like below. The paging section contains meta data about the search result, like number of items returned and total items found. The images section contains information about the images found. Image thumbnail height and width are included with thumbnail URLs. The id can be used to request more detailed information about a specific image.
There are a number of advanced search options available to filter searches beyond just a search word query.
Words to query for. Multiple terms should be separated by a dash or space, for example "cat dog".
Exclude images with these terms. Multiple words should be separated by a dash or space.
The number of results returned per page.
relevant, popular, new,
Horizontal or vertical orientation.
Search for illustrations only, or exclude illustrations from search.
Search for vectors only, or exclude vectors from search.
Exclude editorial use only images from search, or search only for images that can be used for editorial purposes only.
A valid category name from the list available via the categories API request.
Only return images with the specified size and higher; m = medium l = large, xl = extra large. Note: all images have a small size available & vectors will always be returned unless "vectors=n" is specified.
Bigstock does not allow images with nudity. However, some images may be considered suggestive and/or appropriate for adults only. By default, these types of images are not included in the search results. Passing this parameter with a 'n' value will include mature content in the search results.
Restrict searches to a specific contributor ID. Contributor IDs are returned with image detail queries and can be used for attribution and "more by this contributor" links.
en, es, de, pt, it, nl, fr, ja, zh, ru
If a search term returns 0 results in English we will attempt to detect the language the user intended automatically. You can also specify the search language as one of the following: en (English), es (Spanish), de (German), pt (Portuguese), it (Italian), nl (Dutch), fr (French), ja (Japanese), zh (Chinese), ru (Russian).
Get a list of categories that can be searched
The response is in the standard format with the data section containing a list of categories.
The response is in the standard format with the data section containing the image information. Size codes returned correspond to Bigstock image sizes and may be s, m, l, xl, eps, or ai. The eps and ai size codes represent vector images. All other size codes are jpeg images. Please note that every image will not have every size available, though each image is guaranteed to have at least a small available.
Once you have funded your API account you will be able to download full resolution un-watermarked images. Purchasing images requires an authentication key to be passed with each request. The authentication key is generated using the secret key provided and is a combination of the secret key, your account ID and the image ID the user is purchasing. The authentication key is the SHA-1 hash (40 character hexadecimal) of those three data elements.
// Example PHP code to generate auth_key for purchase request
$auth_key = sha1($secret_key . $account_id . $image_id);
The auth_key that is generated needs to be passed with the purchase request. To purchase an image, include the image ID, Size Code and the authentication key.
Note: While using the API in test mode or with an un-funded account, a fixed-resolution test image will always be downloaded instead of the image requested.
Lightboxes & Saved Images
Programmatic access to images saved or added to lightboxes on Bigstock is available via the API. This call allows you to list and show private lightbox content saved under your account, and also to access the details of other user's shared lightboxes via a password key.
Generate an auth_key to access the list of lightboxes in your own account:
// Example PHP code to generate auth_key for lightbox list
$auth_key = sha1($secret_key . $account_id);
To access a private lightbox setup in your account, an auth_key must be specified:
// Example PHP code to generate auth_key for your private lightbox details
$auth_key = sha1($secret_key . $account_id . $lightbox_id);
To access someone else's private lightbox content you must obtain the key for the lightbox (available from the 'share lightbox') link. You must use this key to generate an auth_key and pass it when accessing the private lightbox:
// Example PHP code to generate auth_key for someone else's private lightbox
$auth_key = sha1($secret_key . $account_id . $lightbox_id . $key);
Please include the Bigstock logo within the image selection process in your application. This helps Bigstock image contributors know where images are being used. You should also include a link to http://www.bigstockphoto.com. The Bigstock logo is available for both light and dark backgrounds in two sizes below.