FuzzySearchbeta API Docs

Note that while in beta, the API may be unstable.

Foreword

Currently, you must contact me to obtain a token. I am @Syfaro on Telegram and Twitter. I will ask if you have any plans for its use but currently have no restrictions or price for usage. It is also possible to ask for increased rate limits from the defaults if you have a specific use case.

You may attach your API key to your request via the X-API-Key header. All endpoints support CORS for direct use in browser.

The API base is https://api.fuzzysearch.net.

Image search

This attempts to find similar images to the provided image. It works by generating a perceptual hash of the image and comparing it against the database for similar items. This means it can survive heavy image compression and image resizing. It will not work with cropped images.

It is in the image rate-limit group, which allows for 15 requests per minute.

You may optionally specify a few types of matches for specific needs.

  • type=close — default, starts by attempting to only match identical images for faster results. If no results, expands search. Potentially the slowest.
  • type=exact — fastest, only searches for identical hashes. May miss results.
  • type=force — most inclusive, always searches for more results. Useful if looking for alternate versions.

The top level hash is the hash of the provided image. You may save this if you want to compare it against other results or use it to expand your search later.

The id is an internal identifier unique to each match in the database. site_id and site_id_str are the IDs from their respective sites. The _str variant is provided for convenience working with Twitter, which has IDs greater than can be represented in JavaScript's Number type.

The artists array is not normalized and may contain upper and lowercased versions of the same name. FurAffinity and e621 artist names may not match.

site_info is site-specific information. For FurAffinity it includes the file ID, an integer identifier found in the filename. For e621 it includes the file's md5sum and an array of the sources e621 knows about. You may wish to use these sources to verify FurAffinity results. However they are not normalized and may have variances between URL schemes or paths.

The distance is the hamming distance between the hashes. A distance of 0 means there is a high likelyhood of the images being identical. Anything greater than 2-3 indicates they are unlikely to be an exact match. It is important to note that this hashing does not match our understanding of image similarity. Alternate versions of images can sometimes have similar hashes in the range of 4-10. Matching against artists with nearly identical results can potentially narrow it down to real alternates. The search is limited to images within a distance of 10.

> POST /image?<type>
> image: <multipart data>

{ "hash": 3759002873007294000, "matches": [{ "id": 364827, "site_id": 32634990, "site_id_str": "32634990" "url": "https://d.facdn.net/art/kenket/15656...67.kenket_myaflames.jpg", "filename": "1565637367.kenket_myaflames.jpg", "artists": [ "KenKet" ], "site": "FurAffinity", "site_info": { "file_id": "1565637367" }, "hash": 3759002873007294000, "distance": 0 }, { "id": 4252633, "site_id": 1959646, "site_id_str": "1959646" "url": "https://static1.e621.net/data/73/50/73...16eb7f8310a989740.jpg", "filename": "7350cb150ac62cb16eb7f8310a989740.jpg", "artists": [ "kenket" ], "site": "e621", "site_info": { "file_md5": "7350cb150ac62cb16eb7f8310a989740", "sources": [ "https://www.deviantart.com/kenket/art/...orcery-Soup-809424574" ] }, "hash": 3759002873007294000, "distance": 0 }, { "id": 5097962, "site_id": 1168295833877405696, "site_id_str": "1168295833877405696", "url": "https://pbs.twimg.com/media/EDae3geVAAAvyzf.jpg", "filename": "EDae3geVAAAvyzf.jpg", "artists": [ "tessgarman" ], "site": "Twitter", "hash": 3759002873007294000, "distance": 0 }] }