Image Monitoring API Documentation

Your API Credentials

Your API key will appear here when you login.

Our monitoring API allows you to programatically control your Image Raider account. you can add images, remove images, modify project or account settings, or retrieve reports. The Image Raider website only interfaces with this API, so you can (in theory) do anything through these endpoints that you can via the website’s main UI.


The Request

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

POST /endpoint/ HTTP/1.1
Host: account.imageraider.com
Connection: Close

{"Variables":"go here"}

We achieve this in PHP with the following code:

<?php
$data = array("uid"=>1,"expires"=>12345678,"signature"=>"");
$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

Image Raider 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.
signature: an HMAC-SHA1 hash of your uid, the expires parameter, and your API Key. The secure hash must be base64 encoded then URL-encoded before IncandescentAPI accepts the signature as valid.

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 Signature
$stringToSign = $uid."\n".$expires; 
$binarySignature = hash_hmac('sha1', $stringToSign, $apikey, true);
$signature =urlencode(base64_encode($binarySignature));

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

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


About Projects

Images are grouped in to projects – you can use these however you wish. Agencies can allocate one project per client; photographers often allocate one project per photoshoot, a retailer may allocate one project per product category, etc.

The important note is that results are typically requested on a per-project basis, so it’s best to put images in in the same way that you’ll be taking them out.


Add images to A PROJECT (/add)

You may add as many images as you like to a project within a single request. Add images by including an “images” variable to the JSON object containing an array of image URLs.

Endpoint: https://account.imageraider.com/add/
Variables:
images – a JSON object containing the URLs
project_id – a string of the project you are adding these images to, OR an alphanumeric name (if adding to a project which does not yet exist).

Example PHP code

<?php
$images = array("http://www.domain.com/images/1.jpg","http://www.domain.com/images/2.jpg");
$project_id = "new project about cats"; // OR:
$project_id = 345562; // Pre-existing project_id
$data = array("uid"=>$uid,"expires"=>$expires,"signature"=>$signature,"images"=>$images,"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://account.imageraider.com/add/", FALSE, $context);
?>

The Response

The server will respond with the project_id of this request – this is the unique identifier of this project. The response will be in the form of a JSON object:

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

Get Information about projects and account (/user)

Returns all projects in account, as well as basic user information.

THE REQUEST

Endpoint: https://account.imageraider.com/user/
Example PHP code

<?php
$data = array("uid"=>$uid,"expires"=>$expires,"signature"=>$signature);
$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://account.imageraider.com/user/", FALSE, $context);
?>

THE RESPONSE

This endpoint will return an object containing two objects:

info – information about this user account

  • credit – remaining credits
  • priority – priority of searches over other users
  • usertype – the type of user account (internal metric)
  • package – information about the type of package the user is on
  • notif – notification preferences

projects – a JSON object containing information about each project in the account:

  • project_id – ID of the project
  • project_name – the pretty name of this project
  • freq – an integer of the re-check frequency (in days) – the system will automatically check an image within the projected if it was last checked more than this many days ago
  • queue – the number of images in this project which are currently in the queue to be rechecked
  • notifications – information about the notification settings for this project
  • image_count – the number of images in this project
  • last_check – a UNIX timestamp of the last time an image in this project was checked
  • next_check – a UNIX timestamp of the next time an image in this project will be checked

Example output:

{
    "status": 200,
    "info": {
        "credit": "1234",
        "priority": "10",
        "usertype": "0",
        "last_pay": "0",
        "notif": "n",
    },
    "projects": [{
        "project_id": "1",
        "project_name": "test",
        "freq": "1",
        "queue": null,
        "notifications": "1",
        "sync": {
            "status": false
        },
        "image_count": "4",
        "processing": "0",
        "next_check": "1444427593",
        "last_check": "1444379683"
    }, {
        "project_id": "2",
        "project_name": "DeviantArt",
        "freq": "7",
        "queue": null,
        "notifications": "1",
        "sync": {
            "status": false
        },
        "image_count": "79",
        "processing": "0",
        "next_check": "1444726803",
        "last_check": "1444240825"
    }]
}

Change the frequency of recheck (/set-check-freq)

Image Raider periodically re-checks images for new hosts. You can control the frequency at which it does the by setting its frequency.

THE REQUEST

Endpoint: https://account.imageraider.com/set-check-freq/
Variables:
images OR projects- an object containing either the iid‘s of images, or project_id‘s of projects you wish to change and the frequency that you wish to change it to as a key-value pair.
Example inputs:

i.e. {"iid":"<em>frequency",...}
"images":{"233":"7","234":"7","235":"1","236":"99999"}</em>
{"project_id<em>":"frequency",...}
"projects":{"23":"7","24":"7"}</em>

Example PHP code

<?php
$data = array("uid"=>$uid,"expires"=>$expires,"signature"=>$signature,"projects"=>array("24"=>7));
$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://account.imageraider.com/set-check-freq/", FALSE, $context);
?>

THE RESPONSE

This endpoint will return a success or error message


List the images in a project (/images)

Returns information about the images within a specific project.

THE REQUEST

Endpoint: https://account.imageraider.com/images/
Variables:

project – the project_id you would like to look at
Example PHP code

<?php
$project_id = 12456;
$data = array("uid"=>$uid,"expires"=>$expires,"signature"=>$signature,"project"=>$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://account.imageraider.com/images/", FALSE, $context);
?>

THE RESPONSE

This endpoint will return an object containing all of the images within the project:

  • url – the URL of the image
  • iid – the iid of the image. This is the internal identifier for use with other endpoints.
  • last_check – a UNIX timestamp of the last time this image was checked
  • next_check – a UNIX timestamp of the next time this image will be checked.
  • hosts – the number of hostnames that we know use this image

Remove IMAGES FROM ACCOUNT (/DELETE)

Removes images or projects (and all corresponding data) from your account.

THE REQUEST

Endpoint: https://account.imageraider.com/delete/
Variables:
images – a JSON object containing the the iid of each image you want to delete
OR
projects – a JSON object containing the project_id of each project you want to remove
Example PHP code

<?php
$images = array(5523,14878,899);
// OR:
$project_ids = array(345562); // Pre-existing project_id
$data = array("uid"=>$uid,"expires"=>$expires,"signature"=>$signature,"images"=>$images,"projects"=>$project_ids);
$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://account.imageraider.com/delete/", FALSE, $context);
?>

THE Response

This endpoint will return a list of iid’s or project_id’s which have been removed from your account


Retrieve Results (/report)

This endpoint returns data about the websites found hosting an image (or all of the images within a project)

The Request

Endpoint: https://account.imageraider.com/report/
Variables:
project_id – the project_id of the project you wish to view
datesel – a UNIX timestamp at one minute past midnight of the discovery date that you wish to view. i.e. if you only want to view websites found on the 6th of July, this variable allows that. defaults to “all”
sourcesel – the specific engine that you want to view results from – “google”, “bing”, “yandex”, “baidu”, or “all”. defaults to “all”
Example PHP code

<?php

$data = array("uid"=>$uid,"expires"=>$expires,"signature"=>$signature,"project_id"=>$project_id,"sourcesel"=>"all","datesel"=>all);
$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://account.imageraider.com/report/", 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 – some images are still waiting to be checked (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