Quickstart: Analyze a remote image using the REST API and Java in Computer Vision

In this quickstart, you analyze a remotely stored image to extract visual features by using Computer Vision's REST API. With the Analyze Image method, you can extract visual features based on image content.

If you don't have an Azure subscription, create a free account before you begin.


Create and run the sample application

To create and run the sample, do the following steps:

  1. Create a new Java project in your favorite IDE or editor. If the option is available, create the Java project from a command line application template.
  2. Import the following libraries into your Java project. If you're using Maven, the Maven coordinates are provided for each library.
  3. Add the following import statements to the file that contains the Main public class for your project.

    import java.net.URI;
    import org.apache.http.HttpEntity;
    import org.apache.http.HttpResponse;
    import org.apache.http.client.methods.HttpPost;
    import org.apache.http.entity.StringEntity;
    import org.apache.http.client.utils.URIBuilder;
    import org.apache.http.impl.client.CloseableHttpClient;
    import org.apache.http.impl.client.HttpClientBuilder;
    import org.apache.http.util.EntityUtils;
    import org.json.JSONObject;
  4. Replace the Main public class with the following code, then make the following changes in code where needed:

    1. Replace the value of subscriptionKey with your subscription key.
    2. Replace the value of uriBase with the endpoint URL for the Analyze Image method from the Azure region where you obtained your subscription keys, if necessary.
    3. Optionally, replace the value of imageToAnalyze with the URL of a different image that you want to analyze.
  5. Save, then build the Java project.
  6. If you're using an IDE, run Main. Otherwise, open a command prompt window and then use the java command to run the compiled class. For example, java Main.
public class Main {
    // **********************************************
    // *** Update or verify the following values. ***
    // **********************************************

    // Replace <Subscription Key> with your valid subscription key.
    private static final String subscriptionKey = "<Subscription Key>";

    // You must use the same Azure region in your REST API method as you used to
    // get your subscription keys. For example, if you got your subscription keys
    // from the West US region, replace "westcentralus" in the URL
    // below with "westus".
    // Free trial subscription keys are generated in the West Central US region.
    // If you use a free trial subscription key, you shouldn't need to change
    // this region.
    private static final String uriBase =

    private static final String imageToAnalyze =
            "https://upload.wikimedia.org/wikipedia/commons/" +

    public static void main(String[] args) {
        CloseableHttpClient httpClient = HttpClientBuilder.create().build();

        try {
            URIBuilder builder = new URIBuilder(uriBase);

            // Request parameters. All of them are optional.
            builder.setParameter("visualFeatures", "Categories,Description,Color");
            builder.setParameter("language", "en");

            // Prepare the URI for the REST API method.
            URI uri = builder.build();
            HttpPost request = new HttpPost(uri);

            // Request headers.
            request.setHeader("Content-Type", "application/json");
            request.setHeader("Ocp-Apim-Subscription-Key", subscriptionKey);

            // Request body.
            StringEntity requestEntity =
                    new StringEntity("{\"url\":\"" + imageToAnalyze + "\"}");

            // Call the REST API method and get the response entity.
            HttpResponse response = httpClient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) {
                // Format and display the JSON response.
                String jsonString = EntityUtils.toString(entity);
                JSONObject json = new JSONObject(jsonString);
                System.out.println("REST Response:\n");
        } catch (Exception e) {
            // Display error message.

Examine the response

A successful response is returned in JSON. The sample application parses and displays a successful response in the console window, similar to the following example:

REST Response:

  "metadata": {
    "width": 1826,
    "format": "Jpeg",
    "height": 2436
  "color": {
    "dominantColorForeground": "Brown",
    "isBWImg": false,
    "accentColor": "B74314",
    "dominantColorBackground": "Brown",
    "dominantColors": ["Brown"]
  "requestId": "bbffe1a1-4fa3-4a6b-a4d5-a4964c58a811",
  "description": {
    "captions": [{
      "confidence": 0.8241405091548035,
      "text": "a group of people on a city street filled with traffic at night"
    "tags": [
  "categories": [{
    "score": 0.625,
    "name": "outdoor_street"

Clean up resources

When no longer needed, delete the Java project, including the compiled class and imported libraries.

Next steps

Explore a Java Swing application that uses Computer Vision to perform optical character recognition (OCR); create smart-cropped thumbnails; plus detect, categorize, tag, and describe visual features, including faces, in an image. To rapidly experiment with the Computer Vision API, try the Open API testing console.