NAV Navbar
curl

Introduction

Welcome to the TextDetective API!

This API can be used to easily verify whether user-submitted images contain certain phrases. The best use-case for this API is to pass user-submitted till slips to verify whether the till slip contains certain phrases used for competitions or acitvations.

It is important to keep track of verified images on your side. This API shouldn't be used as a replacement for human verification, but rather as a initial line of verification for a large number of user-submitted images.

We have provided examples of how to make requests using cURL in a Shell session. You can view these examples in the dark area to the right.

Tiers

Other than providing a free tiers for users to experiment with the API (which is quite limited), we also provide Premium tiers with these limitations removed or greatly increased. Inquiries for premium accounts can be requested by sending an email to our Request an Account address.

Free tier limitations

To find out what our premium tiers have to offer, feel free to send us a mail.

Authentication

Get an authentication token

Request

curl "https://textdetective.app/api/authenticate"
  --request POST
  --header "Content-Type: application/json"
  --data '{"client_id": "[your-client-id]", "client_secret": "[your-client-secret]"}'

When you first register your account, you will be provided with a client_id and client_secret value that will be used to request authentication tokens for your account.

Response

{
    "success": true,
    "message": "You have successfully been authenticated",
    "data": {
      "token": "[server-generated-token]",
      "expires": "2018-10-26 13:11:44"
    }
}

HTTP Request

POST https://textdetective.app/api/authenticate

Request Headers

Header Value
Content-Type application/json or multipart/form-data

Query Parameters

Parameter Default Description
client_id No default The client_id you were provided during registration
client_secret No default The client_secret you were provided during registration
lifespan 86400 The amount of seconds this token will be valid. This can be any value between 300 (5 minutes) and 86400 (24 hours)

Using your authentication token

Error Response

{
    "success": false,
    "message": "The authentication credentials required by this request were missing or invalid."
}

All requests you make require you to add a header called Token which value contains the token returned by the authentication call.

If you do not provide this token, or if your token has expired or been replaced (see tier limits), you will see an error similar to the one on the right.

Processing Images

Submit an image for processing

You can submit an image for processing along with all of its search terms. This is done by submitting a multipart/form request with a single image and an array of phrases that you would like to search for.

Request

curl "https://textdetective.app/api/submit"
  --request POST
  --header "Token: [your-authentication-token]"
  --form target=@woolies.jpg
  --form phrase[0]="red pepper hummus"
  --form phrase[1]="Discovery Vitality - VIT"

Response

{
    "success": true,
    "message": "Your processing request has been queued",
    "data": {
      "processing_id": "[server-generated-processing-id]"
    }
}

HTTP Request

POST https://textdetective.app/api/submit

Request Headers

Header Value
Content-Type multipart/form-data
Token The authentication token you obtained by calling the authenticate endpoint

Query Parameters

Parameter Default Description
target No default The image you would like to process. This has to be a valid File of type jpg, png, or bmp
phrase[n] No default The array of search phrases that you would like to look for in the image. The n in brackets denote the index of the array

Please see an example on the right of what a request using cURL in a shell session would look like.

Retrieve an image's processing status

Once an image has been submitted along with its search phrases, it will be pushed onto the back of the queue of other Image Process Requests. If your image is queued or busy processing, you will see one of the responses on the right indicating whether it's Queued or Processing.

Request

curl "https://textdetective.app/api/result?id=[your-processing-id]" 
  --header 'Token: [your-authentication-token]'

Processing Response

{
    "success": true,
    "message": "Your request is still being processed",
    "status_code": 0,
    "status_message": "Queued"
}

OR

{
    "success": true,
    "message": "Your request is still being processed",
    "status_code": 1,
    "status_message": "Processing"
}

Once your image finishes processing, you'll get back a successful response with all of the match data included. See an example of this response on the right.

Success Response

{
  "success": true,
  "message": "Your request has been handled successfully",
  "data": {
    "processing_id": "[your-processing-id]",
    "average_match_percentage": 73,
    "best_match_phrase": "red pepper hummus",
    "best_match_percentage": 100,
    "matches": [
      {
        "search_phrase": "red pepper hummus",
        "matched_phrase": "red pepper hummus",
        "match_percentage": 100
      },
      {
        "search_phrase": "Discovery Vitality - VIT",
        "matched_phrase": " save instantly",
        "match_percentage": 46
      }
    ]
  }
}

HTTP Request

GET https://textdetective.app/api/result

Request Headers

Header Value
Token The authentication token you obtained by calling the authenticate endpoint

Query Parameters

Parameter Default Description
id No default The processing id you obtained by calling the submit endpoint

Errors

The Angle OCR API uses the following error codes:

Error Code Meaning
400 Bad Request - Your request didn't pass the required validation
401 Unauthorized - Your Token is missing or invalid
403 Forbidden - Your account has been deactivated, or you're trying to access someone else's data
404 Not Found - You're trying to access an endpoint that doesn't exist
405 Method Not Allowed - You tried to call an endpoint using the incorrect HTTP Method (GET, POST, PUT, etc.)
429 Too Many Requests - You've reached the hourly limits for your account type
500 Internal Server Error - An issue occurred while handling your request. Please try again later.
503 Service Unavailable - We're temporarily offline for maintenance. Please try again later.