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.
All requests must be sent as JSON objects within the HTTP POST body, i.e.
POST /endpoint/ HTTP/1.1
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:
// 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);
$data = array("uid"=>$uid,"expires"=>$expires,"signature"=>$signature);
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
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).
Image Raider periodically re-checks images for new hosts. You can control the frequency at which it does the by setting its frequency.
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:
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.
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
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)
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
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