How to use the API to classify images

1. Get an authentication token

An authentication token is required to access most API endpoints. To get an authentication token, send a POST request to the token_auth endpoint (URL), providing your CoralNet username and password as POST parameters.

curl example:

curl -H "Content-type: application/vnd.api+json" -d '{"username": "stephen", "password": "my_password"}' https://coralnet.ucsd.edu/api/token_auth/

If all went well, you should get a JSON response (code: 200 OK) with a hex-formatted token, similar to this:

{"token":"f22f560a2186c0380962fc9b6da9b365102ef984"}

If something went wrong, the response status code and/or JSON body should contain details of the error.

2. Request a classifier deployment

Make a request to the deploy endpoint. Your request will need to include the following:

A CoralNet classifier ID. This is the classifier to use for the deployment. To get this, use the CoralNet website to browse to the source you are interested in. The source should have at least one classifier. When you visit the source's main page, you should see a classifier graph like this:

Each dot on the graph represents a classifier. Hover over the dot to see its details.

The 'Global id' is the classifier ID you want here. So if you wanted to use this particular classifier, you would specify a classifier ID of 10726. The rightmost dot is the source's latest classifier and should be the most accurate, but you can also pick an older classifier.

Note that you can only use a classifier from a source that you have view access to. This means either you're a member of the source, or the source is public. If your organization has multiple CoralNet accounts, make sure you chose an account with the relevant source permissions when you obtained an authentication token.

Image URLs. These are the images you want to get classification results for. The deploy endpoint only accepts images that are publicly accessible on the web. If your image is not on the web, you have to upload it somewhere (a website you own, image sharing service, Dropbox account, etc.).

Tip for Dropbox: You can get a working download link for your image by making sure the Dropbox URL has a dl=1 query parameter, as explained in Dropbox help.

Point positions for each image, as row/column pixel positions. These are the points of the image that you want classification results for. Rows are counted top to bottom, and columns are counted left to right, both starting from 0.

You'll specify the image URLs and point positions using JSON. Here is an example specifying 1 image and 2 points:

{
  "data": [
    {
      "type": "image",
      "attributes": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/c/ca/Acropora_coral_ffs.jpg",
        "points": [
          {
            "row": 700,
            "column": 500
          },
          {
            "row": 1100,
            "column": 900
          }
        ]
      }
    }
  ]
}

Finally, make the POST request which includes all of this information, as well as your authorization token. The authorization token goes in an HTTP header called Authorization, the classifier ID goes in the URL, and the images/points JSON goes in the POST data.

curl example:

curl -v -H "Authorization: Token f22f560a2186c0380962fc9b6da9b365102ef984" -H "Content-type: application/vnd.api+json" -d '{"data": [{"type": "image", "attributes": {"url": "https://upload.wikimedia.org/wikipedia/commons/c/ca/Acropora_coral_ffs.jpg", "points": [{"row":700,"column":500}, {"row":1100,"column":900}]}}]}' https://coralnet.ucsd.edu/api/classifier/10726/deploy/

This example uses curl's -v (verbose) option since the response headers are important.

For higher volumes of images/points, you can use curl's @ syntax for reading request data from a file. For example, you can create a file called images.json with the above JSON content, and then use a curl command like this:

curl -v -H "Authorization: Token f22f560a2186c0380962fc9b6da9b365102ef984" -H "Content-type: application/vnd.api+json" -d @images.json https://coralnet.ucsd.edu/api/classifier/10726/deploy/

If successful, the server response should be of '202 Accepted' status, and the Location header should contain the URL that you need to check the status of the classifier deployment. For example, Location: /api/deploy_job/7/status/.

If something went wrong, the response status code and/or JSON body should contain details of the error.

3. Check the status of the classifier deployment

Send a GET request to the URL you got in the previous step.

curl example:

curl -v -H "Authorization: Token f22f560a2186c0380962fc9b6da9b365102ef984" https://coralnet.ucsd.edu/api/deploy_job/7/status/

The response you get will depend on whether the deployment is finished or not. If it's not finished yet, you'll get a '200 OK' response with the following JSON format:

{
  "data": [
    {
      "type": "job",
      "id": "7",
      "attributes": {
        "successes": 0,
        "failures": 1,
        "total": 2,
        "status": "In Progress"
      }
    }
  ]
}

status can either be Pending or In Progress.

If the deployment is finished, you'll get a '303 See Other' response instead, and the Location header should contain the URL that you need to fetch the result of the classifier deployment. For example, Location: /api/deploy_job/7/result/.

4. Fetch the result of the finished classifier deployment

Once the deployment is finished and you've gotten a deploy-result URL as shown in the previous step, send a GET request to that URL.

curl example:

curl -H "Authorization: Token f22f560a2186c0380962fc9b6da9b365102ef984" https://coralnet.ucsd.edu/api/deploy_job/7/result/

The response body should contain the classifier's top 5 labels and scores for each point you requested. Example:

{
  "data": {
    "images": [
      {
        "url": "https://upload.wikimedia.org/wikipedia/commons/c/ca/Acropora_coral_ffs.jpg",
        "points": [
          {
            "row": 700,
            "column": 500,
            "classifications": [
              {
                "label_id": 2093,
                "score": 0.8926345481464616,
                "label_code": "*CORAL",
                "label_name": "CREP-T1 Coral"
              },
              {
                "label_id": 2097,
                "score": 0.03736297079656042,
                "label_code": "*CCA",
                "label_name": "CREP-T1 Crustose coralline algae"
              },
              {
                "label_id": 2096,
                "score": 0.024002975584768303,
                "label_code": "*MA",
                "label_name": "CREP-T1 Macroalgae"
              },
              {
                "label_id": 2098,
                "score": 0.02297470070442297,
                "label_code": "*SED",
                "label_name": "CREP-T1 Sediment"
              },
              {
                "label_id": 2099,
                "score": 0.019182308307261246,
                "label_code": "*TURF",
                "label_name": "CREP-T1 Turf algae"
              }
            ]
          },
          {
            "row": 1100,
            "column": 900,
            "classifications": [
              {
                "label_id": 2099,
                "score": 0.9436883726308904,
                "label_code": "*TURF",
                "label_name": "CREP-T1 Turf algae"
              },
              {
                "label_id": 2097,
                "score": 0.02374941705283773,
                "label_code": "*CCA",
                "label_name": "CREP-T1 Crustose coralline algae"
              },
              {
                "label_id": 2098,
                "score": 0.017043557589485458,
                "label_code": "*SED",
                "label_name": "CREP-T1 Sediment"
              },
              {
                "label_id": 2096,
                "score": 0.012644575484318804,
                "label_code": "*MA",
                "label_name": "CREP-T1 Macroalgae"
              },
              {
                "label_id": 2101,
                "score": 0.0011865575394008235,
                "label_code": "*UC",
                "label_name": "CREP-T1 Unclassified/Unknown benthos"
              }
            ]
          }
        ]
      }
    ]
  }
}

If there was a problem classifying a particular image, the response body will include error messages for that image instead of labels/scores.