README.md

TinEye API PHP Library

tineye-api is a PHP library for the TinEye API. The TinEye API is a paid reverse image search solution for professional, commercial or high-volume users of TinEye.

Contents

• Installation
• Migrating from previous versions
• Getting started
• Methods
  • Common parameters
  • Search using an image URL
  • Search using image data
  • Get remaining searches
  • Get number of indexed images
  • Get the HTTP client
• Support
• Testing
• License

Installation

Install via Composer. If composer is installed, run the following from your shell:

$ composer require tineye/tineye-api

Migrating from previous versions

If you were using any version of the TinEye API library before 2.0.0, you will need to make minor changes to your code.

The API object is now instantiated using a single key, api_key. The value of this key is the same as your previous private_key. The public key is no longer used.

New ✅

<?php
// Sandbox key
// Note that this is the same value as the old private_key
$api_key = '6mm60lsCNIB,FwOWjJqA80QZHh9BMwc-ber4u=t^';
$tineyeapi = new tineye\api\TinEyeApi($api_key);

Old ❌

<?php
// Sandbox keys
$public_key = 'LCkn,2K7osVwkX95K4Oy';
$private_key = '6mm60lsCNIB,FwOWjJqA80QZHh9BMwc-ber4u=t^';
$tineyeapi = new tineye\api\TinEyeApi($private_key, $public_key);

Getting started

Once you've installed the library, you can instantiate a TinEyeApi object with your API key:

<?php
$tineyeapi = new tineye\api\TinEyeApi($api_key);

If you don't have an account yet, you can still test out the library using our API sandbox by instantiating the TinEyeApi object with no arguments:

<?php
$tineyeapi = new tineye\api\TinEyeApi();

Note that the API sandbox will not return real results; all results will be the same image of a cat.

Once you've created your TinEyeApi object you can start searching. You can submit an image using either an image URL or by submitting image data by uploading an image file. You can also check the number of remaining searches in your account or check the number of images in the TinEye index.

Methods

Common parameters

Each search method (searchUrl and searchData) takes an optional parameter params that takes an associative array with any of these options:

<?php
$params = [
    'offset' => 0,
    'limit' => 10,
    'backlink_limit' => 100,
    'sort' => 'score',
    'order' => 'desc',
    'domain' => 'tineye.com',
];

For more information on possible settings please visit the TinEye API documention.

Search using an image URL

Use this method to have TinEye download an image URL and search it against the TinEye index.

<?php
/**
* Search for an image using an image URL
*
* @param String $url Image URL to be downloaded and searched
* @param Array $params Optional General Arguments
* @return Array Multidimensional Array of the returned JSON
*/

$tineyeapi = new tineye\api\TinEyeApi($api_key);
$search_result = $tineyeapi->searchUrl('https://tineye.com/images/meloncat.jpg');

Search using image data

Use this method to upload an image to TinEye and search it against the TinEye index.

<?php
/**
* Search for an image using local image data
* TinEye supports JPEG, PNG, WEBP, GIF, BMP, or TIFF image formats
*
* @param String $image_data fopen stream of an image
* @param String $file_name Name of the file to be uploaded
* @param Array $params Optional General Arguments
*
* @return Array Multidimensional Array of the returned JSON
*/
$tineyeapi = new tineye\api\TinEyeApi($api_key);
$search_result = $tineyeapi->searchData(
    fopen('./tests/meloncat.jpg', 'r'),
    'meloncat.jpg'
);

Get remaining searches

Use this method to get the number and status of remaining search bundles.

<?php
/**
* Returns information on search bundles 
* @return Array Multidimensional array of the returned JSON
*/
$tineyeapi = new tineye\api\TinEyeApi($api_key);
$search_bundles = $tineyeapi->remainingSearches();

Get number of indexed images

Use this method to get the number and images currently indexed by TinEye

<?php
/**
* Returns the count of images in the TinEye index 
* @return Array Multidimensional array of the returned JSON
*/
$tineyeapi = new tineye\api\TinEyeApi($api_key);
$image_count = $tineyeapi->imageCount();

Get the HTTP client

This method allows access to the wrapped GuzzleHttp client. More information is available at GuzzleHttp.

<?php
/**
* Returns the wrapped Guzzle client instance
* @return GuzzleHttp\Client
*/
$tineyeapi = new tineye\api\TinEyeApi($api_key);
$guzzle_client = $tineyeapi->getClient();

Support

Please send comments, recommendations, and bug reports to [email protected].

Testing

Tests are located in the /tests folder and use PHPunit.

$ composer test

License

Licensed under the MIT License (MIT). Please see License File for more information.