unsplash / tinplate Goto Github PK

View Code? Open in Web Editor NEW

13.0 4.0 5.0 53 KB

⭐️ TinEye API wrapper

License: MIT License

Ruby 99.34% Shell 0.66%

tineye api reverse-image-search

tinplate's Introduction

Tinplate

Wrapper 'round the TinEye API.

Installation

Add this line to your application's Gemfile:

gem 'tinplate'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tinplate

Configuration

First you've got to let Tinplate know what your TinEye API keys are. In a Rails app, for example, this would go in an initializer, e.g. config/intitializers/tinplate.rb:

Tinplate.configure do |config|
  config.private_key = "YOUR PRIVATE API KEY"
  config.test        = false
end

If test is set to true (which is also the default), Tinplate will use TinEye's test keys and sandbox environment.

Usage

There are only three API actions available: search, remaining_searches (to check the status of your account), and image_count (if you're curious how many total images TinEye has indexed).

remaining_searches returns an OpenStruct object with three attributes: remaining_searches, start_date, and expire_date.

image_count returns a plain old integer.

Search examples

Search by URL

tineye = Tinplate::TinEye.new
results = tineye.search(image_url: "http://example.com/photo.jpg")

results.stats.total_results    # => 2
results.stats.total_backlinks  # => 3
results.matches                # => an Array of matched images (see below)

results.matches.each do |match|
  # Do what you like with this matched image. The world is your oyster.
end

Search by upload

tineye = Tinplate::TinEye.new
results = tineye.search(image_path: "/home/alice/example.jpg")

Optional search parameters

offset: Default 0
limit: Default 100
sort: "score", "size", or "crawl_date". Default "score".
order: "asc" or "desc". Default "desc".

Example matched image

An OpenStruct object with the following attributes (/w example values):

domain: "ucsb.edu",
top_level_domain: "ucsb.edu",
width: 400
height: 300
size: 50734,
filesize: 195840,
score: 88.9,
tags: ["collection"],
image_url: "http://images.tineye.com/result/0f1e84b7b7538e8e7de048f4d45eb8f579e3e999941b3341ed9a754eb447ebb1",
format: "JPEG",
contributor: true,
overlay: "overlay/507bb6bf9a397284e2330be7c0671aadc7319b4b/0f1e84b7b7538e8e7de048f4d45eb8f579e3e999941b3341ed9a754eb447ebb1?m21=-9.06952e-05&m22=0.999975&m23=0.0295591&m11=0.999975&m13=-0.0171177&m12=9.06952e-05",
backlinks:
  # These are also OpenStruct objects, not Hashes.
  [
    {
      url: "http://example-copier.com/photo.jpg",
      crawl_date: "2012-06-30",
      backlink: "http://example-copier.com/photo.jpg"
    }
  ]

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/unsplash/tinplate. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

tinplate's People

Contributors

Stargazers

Watchers

Forkers

pexels andheartsjaz isabella232 zammalhabe

tinplate's Issues

Support/fixes for new TinEye API changes

TinEye is making breaking API changes:

You need to sign every API request with HMAC-SHA256. Effective immediately we accept HMAC-SHA256 signed requests, for improved security. HMAC-SHA1 signed requests will not work after December 1, 2017. Applications not signing requests with HMAC-SHA256 after that date will stop working.

If your application depends on any of the functionality that is mentioned below, you will need to update your code to reflect the changes. The old API responses will be removed on September 1, 2017. The new version of the API responses are live now at the same endpoints.

Functionality and API response changes
No data has been removed from the API responses, however some data has been reorganized:

We improved the categorization of source websites using domain tags. If a match result was found on a domain we have associated with stock or collection images, this is indicated in the tags list returned from the search call. This replaces the contributor flag which was less specific.

total_backlinks, total_contributors, total_results are now found in the stats dictionary (previously found in the results dictionary).

The remaining_searches call, documented here, returns details for all of your search bundles, not just the currently active bundle. The new total_remaining_searches response variable totals remaining searches across all bundles.

Update authentication method

TinEye says they're changing auth:

To authenticate TinEye API requests, please include your API key in the custom header x-api-key with every API call. Your API key is available on your Getting started page and was formerly called your private key. The new authentication method is currently live and you can begin using it immediately.

Existing auth will continue to work until the end of the year:

This [old] method of signing TinEye API requests will continue to work until December 31, 2021, at which point it will be deprecated.

securerandom and uri in request_authenticator.rb

Hello,

Do securerandom and uri need to be imported in request_authenticator.rb? It won't work for me otherwise.

Also, we would like to add tinplate to our list of TinEye Commercial API libraries if that's okay with you?

Thanks!

Signature errors when uploading

Thanks for this gem! I receive signature errors when uploading images. The same images uploaded work fine.

  tineye = Tinplate::TinEye.new
  tineye_results = tineye.search(image_path: photo_path)
  # raises Tinplate::Error, and a binding.pry before the raise in lib/tinplate/tineye.rb shows it to be due to bad signature
  tineye_results = tineye.search(image_url: photo_url)
  # expected results

if there any tutorial to use in android app

if possible make youtube tutorial hot to use in android app

Faraday

Can you update the dependency of faraday? It seems like it is causing gem compatibility.

`Tinplate::Error.from_response` doesn't seem to work

It looks like from_response is expecting a different API reponse than tineye is giving now.

For example, here is the JSON from some errors I am encountering:

{"code"=>400, "messages"=>["Image too simple or too small to create unique signature"], "stats"=>{}, "results"=>[]}
{"code"=>401, "messages"=>["Please provide a valid API key."], "stats"=>{}, "results"=>[]}

Tinplate::Error.from_response looks like it's expecting the messages array to contain a type but it does not, which means all errors are being turned into a generic Tinplate::Error with no message.

Also there's some errors that are not handled even if this was working: https://help.tineye.com/article/181-list-of-tineye-api-error-messages