Documentation

IncandescentAPI allows you to input image URLs and have the API return a list of websites using those images. Lookups can take anywhere from a few seconds to a full minute – depending on the amount of results and congestion in the queue at that point of time.

If you require dedicated services (which will bring down the amount of waiting time and increase throughput), please contact us.

The Request

All requests must be sent as JSON objects within the HTTP POST body, i.e.

POST /api/add/ HTTP/1.1
Host: incandescent.xyz
Connection: Close

{"Variables":"go here"}

We achieve this in PHP with the following code:

<?php
$data = array("uid"=>1,"expires"=>12345678,"auth"=>"");
$json = json_encode($data);
$context = stream_context_create(array(
 'http' => array(
   "method" => "POST", 
   "Content-Type: application/json\r\n",
   'content' => $json 
 	)
 );
$response = file_get_contents($endpoint, FALSE, $context);

Authentication

IncandescentAPI uses a signed authentication process to verify that it’s you making the request. All requests must include three variables to authenticate the request:
uid: Your user ID
expires: a Unix timestamp (in seconds) indicating how long the request is valid. Expires should be a time no more than twenty minutes ahead of now.
auth: an MD5 hash of your uid, the expires parameter, and your API Key (separated by hyphens).

In PHP, we generate these variables with the following code:

<?php
// UID - this is unique to you
$uid = 1;
// API Key - this is unique to you
$apikey = "";
// Expires - when the signature will become invalid (UNIX timestamp) - may be no more than 1200 seconds from now.
$expires = time()+300;
// Generate auth
$stringToHash = $uid."-".$expires."-".$apikey; 
$auth = md5($stringToHash);

$data = array("uid"=>$uid,"expires"=>$expires,"auth"=>$auth);
?>

Legacy authentication

The original version of Incandescent used a more complicated authentication variable. While deprecated, this authentication method is not going to be sunset – view the documentation

Authentication Errors

400: Malformed request – missing some required (authentication) parameter
701: Signature expired – current time is past the expiry time
702: Signature life is too long (max 1200 seconds)
703: Invalid signature – signature did not match what was required (wrong hash, encoding etc).
704: Missing or invalid uid

Add images to be checked (add)

To perform a reverse image search with IncandescentAPI, you must first add them to the system, and later retrieve the results. From adding the image to being able to retrieve the results, you may have to wait 10 to 60 seconds (depending on congestion).

You may add as many images as you like within a single request, however all results (when retrieved) will be grouped by hostname. Add images by including an “images” variable to the JSON object containing an array of image URLs.

Endpoint: https://incandescent.xyz/api/add/
Cost: 1 credit per URL (multiplied by the multiplier variable – see below)

<?php
$images = array("http://www.domain.com/images/1.jpg","http://www.domain.com/images/2.jpg");
$data = array("uid"=>$uid,"expires"=>$expires,"auth"=>$auth,"images"=>$images,"multiple"=>1);
$json = json_encode($data);
$context = stream_context_create(array(
		'http' => array(
			'method' => 'POST', 
			"Content-Type: application/json\r\n",
			'content' => $json 
		)
	));
$response = file_get_contents("https://incandescent.xyz/api/add/", FALSE, $context);
?>


Check each image multiple times

IncandescentAPI only scrapes the results given by the sources (Google, Bing, etc). In many cases results given to us are incomplete – this is largely due to the data available on the server cluster our scrapers happen to hit, and each search engine limiting search depth due to the computational expense of a comprehensive search. Thus the results returned can vary on a search-by-search basis, and checking an image multiple times can increase the chance of getting more results.

For mission-critical applications, we recommend checking each image multiple times and de-duplicating the results. Incandescent can do this for you through the ‘multiple’ object.

The ‘multiple’ variable sent within the main JSON array tells Incandescent how many times to check each image. All results will be de-duplicated and merged, so it will look the same as if you had requested a single check.

The first check (i.e. default behaviour) costs 1 credit. The cost of each additional check is 0.5 credits, rounded to the nearest credit. It is recommended then, that you only request multiple checks in odd-numbers.

Cost examples:

  • One image checked 11 times: 1 image with a multiple of “11” costs 6 credits per image ((11 – 1 = 10 / 2 = 5) = 6 credits for the request
  • 5 images checked 3 times: 5 images in a request, with a multiple of “3” costs 2 credits per image (3 – 1 = 2 / 2 = 1), = 10 credits for the request.

Usage:

Add a ‘multiple’ object to the main JSON object within your /add/ request:

{"uid":1,"expires":1,"auth":"x","images"=>[...],"multiple":5}

The Response

The server will respond with the project_id of this request – this is the unique identifier which must be passed to the retrieval endpoint to get the websites hosting this image. The response will be in the form of a JSON object:

{"status":200,"project_id":1234567890}

Retrieve Results (get)

After making a request to the *add* endpoint, you should wait at least 5 seconds before calling the *get* endpoint. If a status 710 (try again later) is returned, you should wait at least 2 seconds before calling the get endpoint again.

The Request

Send the project_id (provided from add) within the POST body.
Endpoint: https://incadescent.xyz/api/get/
Cost: Free

<?php

$data = array("uid"=>$uid,"expires"=>$expires,"auth"=>$auth,"project_id"=>$project_id);
$json = json_encode($data);
$context = stream_context_create(array(
		'http' => array(
			'method' => 'POST', 
			"Content-Type: application/json\r\n",
			'content' => $json 
		)
	));
$response = file_get_contents("https://incandescent.xyz/api/get/", FALSE, $context);
?>

The Response

A successful search will return all found pages and data, grouped by hostname.

You may also get the status codes:
710: Try again later (min wait 2 seconds)
755: The search is complete, but no hosts were found.

Sample status response

{"status":710}

Success object sample

 {   "pinterest.com": {
        "pages": {
            "2": {
                "page": "http:\/\/pinterest.com\/pin\/159244536797682708\/",
                "source": "bing",
                "date": 1427788421,
                "usage-image": "http:\/\/media-cache-ec0.pinimg.com\/736x\/04\/cc\/88\/04cc88fe96045b5e05757d148ffee314.jpg",
                "usage-height": "854",
                "usage-width": "570",
                "image": "http:\/\/www.imageraider.com\/tempimg\/5366dfa8815f253f958f3d2563b2dfb4.1427788415",
                "iid": "571894"
            },
             "45": {
                "page": "http:\/\/pinterest.com\/pin\/2342352453453634\/",
                "source": "bing",
                "date": 1427788421,
                "usage-image": "http:\/\/media-cache-ec0.pinimg.com\/736x\/04\/cc\/88\/04cc88fe96045b5e05757d148ffee314.jpg",
                "usage-height": "854",
                "usage-width": "570",
                "image": "http:\/\/www.imageraider.com\/tempimg\/5366dfa8815f253f958f3d2563b2dfb4.1427788415",
                "iid": "571894"
            }
        },
        "meta": {
            "da": "100"
        }
    },
    "www.designboom.com": {
        "pages": {
            "3": {
                "page": "http:\/\/www.designboom.com\/art\/ryan-todd-interview\/",
                "source": "bing",
                "date": 1427788421,
                "usage-image": "http:\/\/www.designboom.com\/wp-content\/uploads\/2013\/07\/18.jpg",
                "usage-height": "578",
                "usage-width": "818",
                "image": "http:\/\/www.imageraider.com\/tempimg\/5366dfa8815f253f958f3d2563b2dfb4.1427788415",
                "iid": "571894"
            }
        },
        "meta": {
            "da": "85.07"
        }
    }
    "id.slideshare.net": {
        "pages": {
            "5": {
                "page": "http:\/\/id.slideshare.net\/bettytsm\/slaid-pekerjaan-beruniform",
                "source": "bing",
                "date": 1427788421,
                "usage-image": "http:\/\/cdn.slidesharecdn.com\/ss_thumbnails\/slaidpekerjaanberuniform-111203195042-phpapp01-thumbnail-4.jpg?cb=1322964398",
                "usage-height": "576",
                "usage-width": "768",
                "image": "http:\/\/www.imageraider.com\/tempimg\/5366dfa8815f253f958f3d2563b2dfb4.1427788415",
                "iid": "571894"
            }
        },
        "meta": {
            "da": "95.61"
        }
    },
    "es.slideshare.net": {
        "pages": {
            "6": {
                "page": "http:\/\/es.slideshare.net\/weffychago\/literatura-hebrea-18763023",
                "source": "bing",
                "date": 1427788421,
                "usage-image": "http:\/\/cdn.slidesharecdn.com\/ss_thumbnails\/diapodcomu-130413210730-phpapp01-thumbnail-4.jpg?cb=1365905295",
                "usage-height": "576",
                "usage-width": "768",
                "image": "http:\/\/www.imageraider.com\/tempimg\/5366dfa8815f253f958f3d2563b2dfb4.1427788415",
                "iid": "571894"
            }
        },
        "meta": {
            "da": "95.61"
        }
    },
}

Returned variables

page – the URL on which the image was found
source – the engine where the usage was found – “google”, “bing”, “yandex”, “baidu”, “other”
date – UNIX timestamp of when it was found (this is a legacy feature recorded for ongoing monitoring purposes)
usage-image – the image which matched the input image
usage-height – height (in pixels) of the usage-image
usage-width – width (in pixels) of the usage-image
image – the URL of the input image
iid – the internal ID of the input image

Remaining credits

You can see the amount of credits remaining in your account by calling the following endpoint with only authentication variables (uid, expires, signature) within the JSON object.

Endpoint: https://incandescent.xyz/api/credit/
Output is a JSON object, i.e:

{"status":200,"credit":100000}

Alternative to using the POST body

Sending a JSON object as the entire post body may be difficult in some languages or frameworks. Instead, you may send the urlencoded JSON object within the POST variable ‘payload’:

POST /api/add/ HTTP/1.1
Host: incandescent.xyz
Connection: Close

payload=%7B%22Variables%22%3A%22go%20here%22%7D

Client libraries

Our client libraries are supplied and maintained by the community. Got one to share? Let us know