API documentation

HTTP API

After having registerd here, you can access to your Pastec index through a simple HTTP API at the URL :

https://api.pastec.io/indexes/<your index id>

For each API call, you must also include a header containing your authentification key:

AuthKey: <your auth key>

Your index id and your API auth key can be found in the API page of the Pastec API manager.

Pastec answers are always formatted in JSON. They contains a mandatory type field that describes the result obtained or an error. Each image has an associated id that is a 32 bit unsigned integer. You must define this id because it establishes the link in the index between the images and their signatures.

All the uploaded images must have their dimensions above 150 pixels. If one of the image dimension exceeds 1000 pixels, the image is resized so that the maximum dimension is set to 1000 pixels and the original aspect ratio is kept.

Here is a detailed list of the API calls:

Adding an image to the index

This call allows to add the signature of an image in the index to make it available for searching. You need to provide the compressed binary data of the image and an id to identify it.

  • URL: https://api.pastec.io/indexes/<your index id>/images/<image id>
  • HTTP method: PUT
  • Data: the binary data of the image to add compressed in JPEG
  • Answer type: "IMAGE_ADDED"
  • Possible error types: "IMAGE_NOT_DECODED", "IMAGE_SIZE_TOO_BIG", "IMAGE_SIZE_TOO_SMALL"
  • Example:
    • Command line:
      curl --header "AuthKey: dummy_auth_key" -X PUT --data-binary @/home/test/img/1.jpg https://api.pastec.io/indexes/dummy_index/images/23
      
    • Answer:
      {
         "image_id" : 23,
         "type" : "IMAGE_ADDED"
      }
      

Removing an image from the index

This call removes the signature of an image in the index thanks to its id. Be careful to not call often this method if your index is big because it is currently very slow.

  • URL: https://api.pastec.io/indexes/<your index id>/images/<image id>
  • HTTP method: DELETE
  • Answer type: "IMAGE_REMOVED"
  • Possible error type: "IMAGE_NOT_FOUND"
  • Example:
    • Command line:
      curl --header "AuthKey: dummy_auth_key" -X DELETE https://api.pastec.io/indexes/dummy_index/images/23
      
    • Answer:
      {
         "image_id" : 23,
         "type" : "IMAGE_REMOVED"
      }
      

Search request

This call performs a search in the index thanks to a request image. It returns the id of the matched images from the most to the least relevant ones.

Request JPEG images with a size approximately equal to 450x340 pixels and a 75% quality are usally enough to achieve a good matching. Their small size allows to quickly send them over a mobile network.

  • URL: https://api.pastec.io/indexes/<your index id>/searcher
  • HTTP method: POST
  • Data: the binary data of the request image compressed in JPEG
  • Answer: "SEARCH_RESULTS" as type field and a list of the the matched image ids from the most to the least relevant one in the "image_ids" field
  • Possible error types: "IMAGE_NOT_DECODED", "IMAGE_SIZE_TOO_BIG", "IMAGE_SIZE_TOO_SMALL"
  • Example:
    • Command line:
      curl --header "AuthKey: dummy_auth_key" -X POST --data-binary @/home/test/img/request.jpg https://api.pastec.io/indexes/dummy_index/searcher
      
    • Answer:
      {
         "image_ids" : [ 2, 5, 43 ],
         "type" : "SEARCH_RESULTS"
      }
      

Clear an index

This call erases all the data currently contained in the index.

  • URL: https://api.pastec.io/indexes/<your index id>/io
  • HTTP method: POST
  • Answer type: "INDEX_CLEARED"
  • Possible error types: -
  • Example:
    • Command line:
      curl --header "AuthKey: dummy_auth_key" -X POST -d '{"type":"CLEAR"}' https://api.pastec.io/indexes/dummy_index/index/io
      
    • Answer:
      {
         "type" : "INDEX_CLEARED"
      }