API Documentation

The Bigstock API provides access to our large repository of images and their associated data. The API is organized around REST concepts and includes a production and testing environment. Any client that can issue a URL request will be able to interact with our API. We return results in JSON and JSONP, which means JavaScript can be used to interact with much of our API. The use of the Bigstock API is bound by acceptance of the Terms of Service.

Our API is divided into 6 types of requests:

  1. Search
  2. Categories
  3. Image Detail
  4. Purchase*
  5. Download*
  6. Lightboxes & Saved Images

* Requires a secret key for authentication

Quick Start & Sample Code

Sample code which implements the search, categories, and image detail API calls is available for your use. The sample is written in JavaScript and can be easily incorporated into any website. jQuery and bootstrap are used in the sample and can be easily swapped out for the framework of your choice.

Overview

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.  

For an alternative & more secure way to authenticate with our API, please see our OAuth documentation here.

To explore, you can interact with most of our API right through your browser. All requests are in the following URL structure:

 api.bigstockphoto.com/[version]/[account id]/[action][?param=value]

For example, to perform a search:

 api.bigstockphoto.com/2/[account id]/search/?q=dog

The API responds with JSON structured data. JSONP is also available for cross-domain javascript requests. Simply add the "&callback=?" parameter to any request to receive JSONP data. The response structure is the same for all of our API queries except download, which will return a file.
All responses from the API will be in the following hiearchy:

{"response_code":200,
"message":"success",
"data":{
    ...
    }
}

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.

 testapi.bigstockphoto.com/2/[account id]/search/?q=dog


SSL / HTTPS

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.

 

{"response_code":200,
"message":"success",
"data":{
    "paging":
        {"items":75,
        "items_per_page":80,
        "total_items":5477320,
        "page":1,
        "total_pages":68467},
    "images":[
        {"id":80443,
        "title":"E-Business",
        "small_thumb":
            {"url":"http://static3.bigstockphoto.com/thumbs/4/0/8/small2/80443.jpg",
            "width":170,
            "height":121}
        },
        {"id":755262,
        "title":"Unity and Strength",
        "small_thumb":
            {"url":"http://static2.bigstockphoto.com/thumbs/5/5/7/small2/755262.jpg",
            "width":170,
            "height":131}
        },
        ...
    ]
    }
}

 

Extended Search Results with additional meta data are available by adding the parameter response_detail=all. The data returned is similar to the individual image detail call (shown further down).

api.bigstockphoto.com/2/[account id]/search/?q=dog&response_detail=all

 

{
    "response_code": 200, 
    "message": "success", 
    "data": {
        "paging": {
            "items": 46, 
            "items_per_page": 50, 
            "total_items": 98459, 
            "page": 1, 
            "total_pages": 1970
        }, 
        "images": [
            {
                "id": 203689, 
                "title": "Dog", 
                "description": "dog", 
                "small_thumb": {
                    "url": "http://static9.bigstockphoto.com/thumbs/3/0/2/small2/203689.jpg", 
                    "width": 170, 
                    "height": 113
                }, 
                "preview": {
                    "url": "http://static2.bigstockphoto.com/thumbs/3/0/2/large2/203689.jpg", 
                    "width": 450, 
                    "height": 300
                }, 
                "keywords": "animal,dog,grass,green,landscape,nature,pet,sit,sitting,sky", 
                "contributor": "newart_pictures"},
        ...
        ]
    }
}


Advanced Search Options

There are a number of advanced search options available to filter searches beyond just a search word query.

Parameter Values Default Notes
q text - Words to query for. Multiple terms should be separated by a dash or space, for example "cat dog".
exclude text - Exclude images with these terms. Multiple words should be separated by a dash or space.
page # 1  
limit 1-200 50  The number of results returned per page.
order relevant, popular, new, popular  
orientation h, v - Horizontal or vertical orientation.
illustrations y, n - Search for illustrations only, or exclude illustrations from search.
vectors y, n - Search for vectors only, or exclude vectors from search.
editorial Y, N N Exclude editorial use only images from search, or search only for images that can be used for editorial purposes only.
category text - A valid category name from the list available via the categories API request.
size m,l,xl - 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.
safesearch y, n y 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. 
contributor text - 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.
language en, es, de, pt, it, nl, fr, ja, zh, ru, cs, da, fi, hu, ko, nb, pl, sv, th, tr en

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), cs (Czech), da (Danish), fi (Finnish), hu (Hungarian), ko (Korean), nb (Norwegian), pl (Polish), sv (Swedish), th (Thai), tr (Turkish).


Categories

Get a list of categories that can be searched

api.bigstockphoto.com/2/[account id]/categories/

The response is in the standard format with the data section containing a list of categories.

{"response_code":200,
"message":"success",
"data":
[
   {"name":"Abstract"},
   {"name":"Animals"},
   {"name":"Architecture"}
   ...
  ]
} }

 

Image Detail

The image ID returned in a search result can be used to query for more information about a specific image.

 api.bigstockphoto.com/2/[account id]/image/1326961


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.

{
    "response_code": 200, 
    "message": "success", 
    "data": {
        "image": {
            "id": 1326961, 
            "title": "Crazy Guy Cartoon", 
            "description": "crazy guy cartoon eps of a crazy guy", 
            "preview": {
                "url": "http://static2.bigstockphoto.com/thumbs/2/3/1/large2/1326961.jpg", 
                "width": 268, 
                "height": 450
            }, 
            "formats": [
                {
                    "label": "small", 
                    "size_code": "s", 
                    "width": 537, 
                    "height": 900
                }, 
                {
                    "label": "medium", 
                    "size_code": "m", 
                    "width": 955, 
                    "height": 1600
                }, 
                {
                    "label": "large", 
                    "size_code": "l", 
                    "width": 1792, 
                    "height": 3000
                }, 
                {
                    "label": "vector", 
                    "size_code": "eps", 
                    "width": 453, 
                    "height": 758
                }
            ], 
            "categories": [
                {
                    "name": "Conceptual:Humorous"
                }, 
                {
                    "name": "Art-Illustration:2D"
                }, 
                {
                    "name": "Art-Illustration:Vector"
                }
            ], 
            "keywords": "big,cartoon,crazy,funny,green,guy,hair,head,humor,humorous,insane,insanity,lunatic,man,sick,stupid,teeth,tongue,ugly,wacky", 
            "contributor": "Tim"
        }
    }
}

 

Purchase

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.

 api.bigstockphoto.com/2/[account id]/purchase?image_id=[image id]&size_code=[size code]&auth_key=[auth_key]


If the purchase is approved, a download ID will be returned which can then be used to download the image file.

{"response_code":200,
"message":"success",
"data":{
    "currency_amount":2.99,
    "currency_code":"USD",
    "download_id":724111049}
}


Download

Downloading a file also requires an authentication key to be passed with the download request. The download key is generated using the secret key, account ID and download ID.

// Example PHP code to generate auth_key for purchase request
$auth_key = sha1($secret_key . $account_id . $download_id);


The download request URL must include the generated auth_key  and download_id returned by the purchase request. In the event of an error, the response header should be checked for error information.

 api.bigstockphoto.com/2/[account id]/download?auth_key=[auth_key]&download_id=[download_id]

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. 

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);

Get a list of your lightboxes:

api.bigstockphoto.com/2/[account id]/lightbox/?auth_key=[auth key]

 Response:

{
    "response_code": 200, 
    "message": "success", 
    "data": {
        "total_items": 3, 
        "lightboxes": [
            {
                "id": 1382, 
                "title": "Transportation", 
                "items": 23
            }, 
            {
                "id": 212, 
                "title": "Saved", 
                "items": 4
            }, 
            {
                "id": 131, 
                "title": "Favorites", 
                "items": 92
            }
        ]
    }
}

 

Public lightbox content does not require an auth_key and can be accessed directly with the id of the lightbox:

api.bigstockphoto.com/2/[account id]/lightbox/[lightbox id]/

 

page and limit can be set in the same way as described in advanced search options:

api.bigstockphoto.com/2/[account id]/lightbox/[lightbox id]/?page=2&limit=5

 

{
    "response_code": 200, 
    "message": "success", 
    "data": {
        "page": {
            "items": 5, 
            "items_per_page": 5, 
            "total_items": 28, 
            "page": 2, 
            "total_pages": 6
        }, 
        "lightbox": {
            "id": 2063210, 
            "name": "Transportation", 
            "items": 28
        }, 
        "images": [
            {
                "id": 26953016, 
                "title": "Vintage photo of young man on scooter (fifties/sixties)", 
                "small_thumb": {
                    "url": "http://static6.bigstockphoto.com/thumbs/9/6/2/small2/26953016.jpg", 
                    "width": 120, 
                    "height": 170
                }
            }, 
            {
                "id": 27089681, 
                "title": "Scribble boy riding scooter", 
                "small_thumb": {
                    "url": "http://static1.bigstockphoto.com/thumbs/0/7/2/small2/27089681.jpg", 
                    "width": 170, 
                    "height": 170
                }
            }, 
            ...
        ]
    }
}

 

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);

 


Logo

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. 

bigstock-black-medium.png  bigstock-black-small.png
bigstock-white-medium.png   bigstock-white-small.png
Was this article helpful?
1 out of 2 found this helpful
Have more questions? Submit a request

Comments

Please sign in to leave a comment.