Detecting Web Entities and Pages

Web Detection detects Web references to an image.

Running Web Detection on a local image

Protocol

Refer to the images:annotate API endpoint for complete details.

To perform Web Detection, make a POST request and provide the appropriate request body:

POST https://vision.googleapis.com/v1/images:annotate?key=YOUR_API_KEY
{
  "requests": [
    {
      "image": {
        "content": "/9j/7QBEUGhvdG9zaG9...base64-encoded-image-content...fXNWzvDEeYxxxzj/Coa6Bax//Z"
      },
      "features": [
        {
          "type": "WEB_DETECTION"
        }
      ]
    }
  ]
}

See the AnnotateImageRequest reference documentation for more information on configuring the request body.

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format:

{
  "responses": [
    {
      "webDetection": {
        "webEntities": [
          {
            "entityId": "/m/0105pbj4",
            "score": 0.99534,
            "description": "Google Cloud Platform"
          },
        ],
        "partialMatchingImages": [
          {
            "url": "https://example.com/path/img.png",
            "score": 0.01
          },
        ],
        "pagesWithMatchingImages": [
          {
            "url": "https://status.cloud.google.com/",
            "score": 0.87187254
          },
        ],
        "bestGuessLabels": [
          {
            "label": "landmark"
          }
        ]
      }
    }
  ]
}

C#

Before trying this sample, follow the C# setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API C# API reference documentation .

// Load an image from a local file.
var image = Image.FromFile(filePath);
var client = ImageAnnotatorClient.Create();
WebDetection annotation = client.DetectWebInformation(image);
foreach (var matchingImage in annotation.FullMatchingImages)
{
    Console.WriteLine("MatchingImage Score:\t{0}\tUrl:\t{1}",
        matchingImage.Score, matchingImage.Url);
}
foreach (var page in annotation.PagesWithMatchingImages)
{
    Console.WriteLine("PageWithMatchingImage Score:\t{0}\tUrl:\t{1}",
        page.Score, page.Url);
}
foreach (var matchingImage in annotation.PartialMatchingImages)
{
    Console.WriteLine("PartialMatchingImage Score:\t{0}\tUrl:\t{1}",
        matchingImage.Score, matchingImage.Url);
}
foreach (var entity in annotation.WebEntities)
{
    Console.WriteLine("WebEntity Score:\t{0}\tId:\t{1}\tDescription:\t{2}",
        entity.Score, entity.EntityId, entity.Description);
}

Go

Before trying this sample, follow the Go setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Go API reference documentation .

// detectWeb gets image properties from the Vision API for an image at the given file path.
func detectWeb(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}

	f, err := os.Open(file)
	if err != nil {
		return err
	}
	defer f.Close()

	image, err := vision.NewImageFromReader(f)
	if err != nil {
		return err
	}
	web, err := client.DetectWeb(ctx, image, nil)
	if err != nil {
		return err
	}

	fmt.Fprintln(w, "Web properties:")
	if len(web.FullMatchingImages) != 0 {
		fmt.Fprintln(w, "\tFull image matches:")
		for _, full := range web.FullMatchingImages {
			fmt.Fprintf(w, "\t\t%s\n", full.Url)
		}
	}
	if len(web.PagesWithMatchingImages) != 0 {
		fmt.Fprintln(w, "\tPages with this image:")
		for _, page := range web.PagesWithMatchingImages {
			fmt.Fprintf(w, "\t\t%s\n", page.Url)
		}
	}
	if len(web.WebEntities) != 0 {
		fmt.Fprintln(w, "\tEntities:")
		fmt.Fprintln(w, "\t\tEntity\t\tScore\tDescription")
		for _, entity := range web.WebEntities {
			fmt.Fprintf(w, "\t\t%-14s\t%-2.4f\t%s\n", entity.EntityId, entity.Score, entity.Description)
		}
	}
	if len(web.BestGuessLabels) != 0 {
		fmt.Fprintln(w, "\tBest guess labels:")
		for _, label := range web.BestGuessLabels {
			fmt.Fprintf(w, "\t\t%s\n", label.Label)
		}
	}

	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Java API reference documentation .

/**
 * Finds references to the specified image on the web.
 *
 * @param filePath The path to the local file used for web annotation detection.
 * @param out A {@link PrintStream} to write the results to.
 * @throws Exception on errors while closing the client.
 * @throws IOException on Input/Output errors.
 */
public static void detectWebDetections(String filePath, PrintStream out) throws Exception,
    IOException {
  List<AnnotateImageRequest> requests = new ArrayList<>();

  ByteString imgBytes = ByteString.readFrom(new FileInputStream(filePath));

  Image img = Image.newBuilder().setContent(imgBytes).build();
  Feature feat = Feature.newBuilder().setType(Type.WEB_DETECTION).build();
  AnnotateImageRequest request =
      AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
  requests.add(request);

  try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
    BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
    List<AnnotateImageResponse> responses = response.getResponsesList();

    for (AnnotateImageResponse res : responses) {
      if (res.hasError()) {
        out.printf("Error: %s\n", res.getError().getMessage());
        return;
      }

      // Search the web for usages of the image. You could use these signals later
      // for user input moderation or linking external references.
      // For a full list of available annotations, see http://g.co/cloud/vision/docs
      WebDetection annotation = res.getWebDetection();
      out.println("Entity:Id:Score");
      out.println("===============");
      for (WebEntity entity : annotation.getWebEntitiesList()) {
        out.println(entity.getDescription() + " : " + entity.getEntityId() + " : "
            + entity.getScore());
      }
      for (WebLabel label : annotation.getBestGuessLabelsList()) {
        out.format("\nBest guess label: %s", label.getLabel());
      }
      out.println("\nPages with matching images: Score\n==");
      for (WebPage page : annotation.getPagesWithMatchingImagesList()) {
        out.println(page.getUrl() + " : " + page.getScore());
      }
      out.println("\nPages with partially matching images: Score\n==");
      for (WebImage image : annotation.getPartialMatchingImagesList()) {
        out.println(image.getUrl() + " : " + image.getScore());
      }
      out.println("\nPages with fully matching images: Score\n==");
      for (WebImage image : annotation.getFullMatchingImagesList()) {
        out.println(image.getUrl() + " : " + image.getScore());
      }
      out.println("\nPages with visually similar images: Score\n==");
      for (WebImage image : annotation.getVisuallySimilarImagesList()) {
        out.println(image.getUrl() + " : " + image.getScore());
      }
    }
  }
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Node.js API reference documentation .

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ImageAnnotatorClient();

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const fileName = 'Local image file, e.g. /path/to/image.png';

// Detect similar images on the web to a local file
client
  .webDetection(fileName)
  .then(results => {
    const webDetection = results[0].webDetection;

    if (webDetection.fullMatchingImages.length) {
      console.log(
        `Full matches found: ${webDetection.fullMatchingImages.length}`
      );
      webDetection.fullMatchingImages.forEach(image => {
        console.log(`  URL: ${image.url}`);
        console.log(`  Score: ${image.score}`);
      });
    }

    if (webDetection.partialMatchingImages.length) {
      console.log(
        `Partial matches found: ${webDetection.partialMatchingImages.length}`
      );
      webDetection.partialMatchingImages.forEach(image => {
        console.log(`  URL: ${image.url}`);
        console.log(`  Score: ${image.score}`);
      });
    }

    if (webDetection.webEntities.length) {
      console.log(`Web entities found: ${webDetection.webEntities.length}`);
      webDetection.webEntities.forEach(webEntity => {
        console.log(`  Description: ${webEntity.description}`);
        console.log(`  Score: ${webEntity.score}`);
      });
    }

    if (webDetection.bestGuessLabels.length) {
      console.log(
        `Best guess labels found: ${webDetection.bestGuessLabels.length}`
      );
      webDetection.bestGuessLabels.forEach(label => {
        console.log(`  Label: ${label.label}`);
      });
    }
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

Before trying this sample, follow the PHP setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API PHP API reference documentation .

namespace Google\Cloud\Samples\Vision;

use Google\Cloud\Vision\V1\ImageAnnotatorClient;

// $path = 'path/to/your/image.jpg'

function detect_web($path)
{
    $imageAnnotator = new ImageAnnotatorClient();

    # annotate the image
    $image = file_get_contents($path);
    $response = $imageAnnotator->webDetection($image);
    $web = $response->getWebDetection();

    // Print best guess labels
    printf('%d best guess labels found' . PHP_EOL,
        count($web->getBestGuessLabels()));
    foreach ($web->getBestGuessLabels() as $label) {
        printf('Best guess label: %s' . PHP_EOL, $label->getLabel());
    }
    print(PHP_EOL);

    // Print pages with matching images
    printf('%d pages with matching images found' . PHP_EOL,
        count($web->getPagesWithMatchingImages()));
    foreach ($web->getPagesWithMatchingImages() as $page) {
        printf('URL: %s' . PHP_EOL, $page->getUrl());
    }
    print(PHP_EOL);

    // Print full matching images
    printf('%d full matching images found' . PHP_EOL,
        count($web->getFullMatchingImages()));
    foreach ($web->getFullMatchingImages() as $fullMatchingImage) {
        printf('URL: %s' . PHP_EOL, $fullMatchingImage->getUrl());
    }
    print(PHP_EOL);

    // Print partial matching images
    printf('%d partial matching images found' . PHP_EOL,
        count($web->getPartialMatchingImages()));
    foreach ($web->getPartialMatchingImages() as $partialMatchingImage) {
        printf('URL: %s' . PHP_EOL, $partialMatchingImage->getUrl());
    }
    print(PHP_EOL);

    // Print visually similar images
    printf('%d visually similar images found' . PHP_EOL,
        count($web->getVisuallySimilarImages()));
    foreach ($web->getVisuallySimilarImages() as $visuallySimilarImage) {
        printf('URL: %s' . PHP_EOL, $visuallySimilarImage->getUrl());
    }
    print(PHP_EOL);

    // Print web entities
    printf('%d web entities found' . PHP_EOL,
        count($web->getWebEntities()));
    foreach ($web->getWebEntities() as $entity) {
        printf('Description: %s, Score %s' . PHP_EOL,
            $entity->getDescription(),
            $entity->getScore());
    }

    $imageAnnotator->close();
}

Python

Before trying this sample, follow the Python setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Python API reference documentation .

def detect_web(path):
    """Detects web annotations given an image."""
    client = vision.ImageAnnotatorClient()

    with io.open(path, 'rb') as image_file:
        content = image_file.read()

    image = vision.types.Image(content=content)

    response = client.web_detection(image=image)
    annotations = response.web_detection

    if annotations.best_guess_labels:
        for label in annotations.best_guess_labels:
            print('\nBest guess label: {}'.format(label.label))

    if annotations.pages_with_matching_images:
        print('\n{} Pages with matching images found:'.format(
            len(annotations.pages_with_matching_images)))

        for page in annotations.pages_with_matching_images:
            print('\n\tPage url   : {}'.format(page.url))

            if page.full_matching_images:
                print('\t{} Full Matches found: '.format(
                       len(page.full_matching_images)))

                for image in page.full_matching_images:
                    print('\t\tImage url  : {}'.format(image.url))

            if page.partial_matching_images:
                print('\t{} Partial Matches found: '.format(
                       len(page.partial_matching_images)))

                for image in page.partial_matching_images:
                    print('\t\tImage url  : {}'.format(image.url))

    if annotations.web_entities:
        print('\n{} Web entities found: '.format(
            len(annotations.web_entities)))

        for entity in annotations.web_entities:
            print('\n\tScore      : {}'.format(entity.score))
            print(u'\tDescription: {}'.format(entity.description))

    if annotations.visually_similar_images:
        print('\n{} visually similar images found:\n'.format(
            len(annotations.visually_similar_images)))

        for image in annotations.visually_similar_images:
            print('\tImage url    : {}'.format(image.url))

Ruby

Before trying this sample, follow the Ruby setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Ruby API reference documentation .

# project_id = "Your Google Cloud project ID"
# image_path = "Path to local image file, eg. './image.png'"

require "google/cloud/vision"

vision = Google::Cloud::Vision.new project: project_id
image  = vision.image image_path

web = image.web

web.entities.each do |entity|
  puts entity.description
end

web.full_matching_images.each do |image|
  puts image.url
end

Running Web Detection on a remote image

For your convenience, the Vision API can perform Web Detection directly on an image file located in Google Cloud Storage or on the Web without the need to send the contents of the image file in the body of your request.

Protocol

Refer to the images:annotate API endpoint for complete details.

To perform Web Detection, make a POST request and provide the appropriate request body:

POST https://vision.googleapis.com/v1/images:annotate?key=YOUR_API_KEY
{
  "requests": [
    {
      "image": {
        "source": {
          "gcsImageUri": "gs://YOUR_BUCKET_NAME/YOUR_FILE_NAME"
        }
      },
      "features": [
        {
          "type": "WEB_DETECTION"
        }
      ]
    }
  ]
}

See the AnnotateImageRequest reference documentation for more information on configuring the request body.

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format:

{
  "responses": [
    {
      "webDetection": {
        "webEntities": [
          {
            "entityId": "/m/0105pbj4",
            "score": 0.99534,
            "description": "Google Cloud Platform"
          },
        ],
        "partialMatchingImages": [
          {
            "url": "https://example.com/path/img.png",
            "score": 0.01
          },
        ],
        "pagesWithMatchingImages": [
          {
            "url": "https://status.cloud.google.com/",
            "score": 0.87187254
          },
        ],
        "bestGuessLabels": [
          {
            "label": "landmark"
          }
        ]
      }
    }
  ]
}

C#

Before trying this sample, follow the C# setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API C# API reference documentation .

// Specify a Google Cloud Storage uri for the image
// or a publicly accessible HTTP or HTTPS uri.
var image = Image.FromUri(uri);
var client = ImageAnnotatorClient.Create();
WebDetection annotation = client.DetectWebInformation(image);
foreach (var matchingImage in annotation.FullMatchingImages)
{
    Console.WriteLine("MatchingImage Score:\t{0}\tUrl:\t{1}",
        matchingImage.Score, matchingImage.Url);
}
foreach (var page in annotation.PagesWithMatchingImages)
{
    Console.WriteLine("PageWithMatchingImage Score:\t{0}\tUrl:\t{1}",
        page.Score, page.Url);
}
foreach (var matchingImage in annotation.PartialMatchingImages)
{
    Console.WriteLine("PartialMatchingImage Score:\t{0}\tUrl:\t{1}",
        matchingImage.Score, matchingImage.Url);
}
foreach (var entity in annotation.WebEntities)
{
    Console.WriteLine("WebEntity Score:\t{0}\tId:\t{1}\tDescription:\t{2}",
        entity.Score, entity.EntityId, entity.Description);
}

Go

Before trying this sample, follow the Go setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Go API reference documentation .

// detectWeb gets image properties from the Vision API for an image at the given file path.
func detectWebURI(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}

	image := vision.NewImageFromURI(file)
	web, err := client.DetectWeb(ctx, image, nil)
	if err != nil {
		return err
	}

	fmt.Fprintln(w, "Web properties:")
	if len(web.FullMatchingImages) != 0 {
		fmt.Fprintln(w, "\tFull image matches:")
		for _, full := range web.FullMatchingImages {
			fmt.Fprintf(w, "\t\t%s\n", full.Url)
		}
	}
	if len(web.PagesWithMatchingImages) != 0 {
		fmt.Fprintln(w, "\tPages with this image:")
		for _, page := range web.PagesWithMatchingImages {
			fmt.Fprintf(w, "\t\t%s\n", page.Url)
		}
	}
	if len(web.WebEntities) != 0 {
		fmt.Fprintln(w, "\tEntities:")
		fmt.Fprintln(w, "\t\tEntity\t\tScore\tDescription")
		for _, entity := range web.WebEntities {
			fmt.Fprintf(w, "\t\t%-14s\t%-2.4f\t%s\n", entity.EntityId, entity.Score, entity.Description)
		}
	}
	if len(web.BestGuessLabels) != 0 {
		fmt.Fprintln(w, "\tBest guess labels:")
		for _, label := range web.BestGuessLabels {
			fmt.Fprintf(w, "\t\t%s\n", label.Label)
		}
	}

	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Java API reference documentation .

/**
 * Detects whether the remote image on Google Cloud Storage has features you would want to
 * moderate.
 *
 * @param gcsPath The path to the remote on Google Cloud Storage file to detect web annotations.
 * @param out A {@link PrintStream} to write the results to.
 * @throws Exception on errors while closing the client.
 * @throws IOException on Input/Output errors.
 */
public static void detectWebDetectionsGcs(String gcsPath, PrintStream out) throws Exception,
    IOException {
  List<AnnotateImageRequest> requests = new ArrayList<>();

  ImageSource imgSource = ImageSource.newBuilder().setGcsImageUri(gcsPath).build();
  Image img = Image.newBuilder().setSource(imgSource).build();
  Feature feat = Feature.newBuilder().setType(Type.WEB_DETECTION).build();
  AnnotateImageRequest request =
      AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
  requests.add(request);

  try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
    BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
    List<AnnotateImageResponse> responses = response.getResponsesList();

    for (AnnotateImageResponse res : responses) {
      if (res.hasError()) {
        out.printf("Error: %s\n", res.getError().getMessage());
        return;
      }

      // Search the web for usages of the image. You could use these signals later
      // for user input moderation or linking external references.
      // For a full list of available annotations, see http://g.co/cloud/vision/docs
      WebDetection annotation = res.getWebDetection();
      out.println("Entity:Id:Score");
      out.println("===============");
      for (WebEntity entity : annotation.getWebEntitiesList()) {
        out.println(entity.getDescription() + " : " + entity.getEntityId() + " : "
            + entity.getScore());
      }
      for (WebLabel label : annotation.getBestGuessLabelsList()) {
        out.format("\nBest guess label: %s", label.getLabel());
      }
      out.println("\nPages with matching images: Score\n==");
      for (WebPage page : annotation.getPagesWithMatchingImagesList()) {
        out.println(page.getUrl() + " : " + page.getScore());
      }
      out.println("\nPages with partially matching images: Score\n==");
      for (WebImage image : annotation.getPartialMatchingImagesList()) {
        out.println(image.getUrl() + " : " + image.getScore());
      }
      out.println("\nPages with fully matching images: Score\n==");
      for (WebImage image : annotation.getFullMatchingImagesList()) {
        out.println(image.getUrl() + " : " + image.getScore());
      }
      out.println("\nPages with visually similar images: Score\n==");
      for (WebImage image : annotation.getVisuallySimilarImagesList()) {
        out.println(image.getUrl() + " : " + image.getScore());
      }
    }
  }
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Node.js API reference documentation .

// Imports the Google Cloud client libraries
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ImageAnnotatorClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Bucket where the file resides, e.g. my-bucket';
// const fileName = 'Path to file within bucket, e.g. path/to/image.png';

// Detect similar images on the web to a remote file
client
  .webDetection(`gs://${bucketName}/${fileName}`)
  .then(results => {
    const webDetection = results[0].webDetection;

    if (webDetection.fullMatchingImages.length) {
      console.log(
        `Full matches found: ${webDetection.fullMatchingImages.length}`
      );
      webDetection.fullMatchingImages.forEach(image => {
        console.log(`  URL: ${image.url}`);
        console.log(`  Score: ${image.score}`);
      });
    }

    if (webDetection.partialMatchingImages.length) {
      console.log(
        `Partial matches found: ${webDetection.partialMatchingImages.length}`
      );
      webDetection.partialMatchingImages.forEach(image => {
        console.log(`  URL: ${image.url}`);
        console.log(`  Score: ${image.score}`);
      });
    }

    if (webDetection.webEntities.length) {
      console.log(`Web entities found: ${webDetection.webEntities.length}`);
      webDetection.webEntities.forEach(webEntity => {
        console.log(`  Description: ${webEntity.description}`);
        console.log(`  Score: ${webEntity.score}`);
      });
    }

    if (webDetection.bestGuessLabels.length) {
      console.log(
        `Best guess labels found: ${webDetection.bestGuessLabels.length}`
      );
      webDetection.bestGuessLabels.forEach(label => {
        console.log(`  Label: ${label.label}`);
      });
    }
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

Before trying this sample, follow the PHP setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API PHP API reference documentation .

namespace Google\Cloud\Samples\Vision;

use Google\Cloud\Vision\V1\ImageAnnotatorClient;

// $path = 'gs://path/to/your/image.jpg'

function detect_web_gcs($path)
{
    $imageAnnotator = new ImageAnnotatorClient();

    # annotate the image
    $response = $imageAnnotator->webDetection($path);
    $web = $response->getWebDetection();

    if ($web) {
        printf('%d best guess labels found' . PHP_EOL,
            count($web->getPagesWithMatchingImages()));
        foreach ($web->getBestGuessLabels() as $label) {
            printf('Best guess label: %s' . PHP_EOL, $label->getLabel());
        }
        print(PHP_EOL);

        // Print pages with matching images
        printf('%d pages with matching images found' . PHP_EOL,
            count($web->getPagesWithMatchingImages()));
        foreach ($web->getPagesWithMatchingImages() as $page) {
            printf('URL: %s' . PHP_EOL, $page->getUrl());
        }
        print(PHP_EOL);

        // Print full matching images
        printf('%d full matching images found' . PHP_EOL,
            count($web->getFullMatchingImages()));
        foreach ($web->getFullMatchingImages() as $fullMatchingImage) {
            printf('URL: %s' . PHP_EOL, $fullMatchingImage->getUrl());
        }
        print(PHP_EOL);

        // Print partial matching images
        printf('%d partial matching images found' . PHP_EOL,
            count($web->getPartialMatchingImages()));
        foreach ($web->getPartialMatchingImages() as $partialMatchingImage) {
            printf('URL: %s' . PHP_EOL, $partialMatchingImage->getUrl());
        }
        print(PHP_EOL);

        // Print visually similar images
        printf('%d visually similar images found' . PHP_EOL,
            count($web->getVisuallySimilarImages()));
        foreach ($web->getVisuallySimilarImages() as $visuallySimilarImage) {
            printf('URL: %s' . PHP_EOL, $visuallySimilarImage->getUrl());
        }
        print(PHP_EOL);

        // Print web entities
        printf('%d web entities found' . PHP_EOL,
            count($web->getWebEntities()));
        foreach ($web->getWebEntities() as $entity) {
            printf('Description: %s, Score: %f' . PHP_EOL,
                $entity->getDescription(),
                $entity->getScore());
        }
    } else {
        print('No Results.' . PHP_EOL);
    }

    $imageAnnotator->close();
}

Python

Before trying this sample, follow the Python setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Python API reference documentation .

def detect_web_uri(uri):
    """Detects web annotations in the file located in Google Cloud Storage."""
    client = vision.ImageAnnotatorClient()
    image = vision.types.Image()
    image.source.image_uri = uri

    response = client.web_detection(image=image)
    annotations = response.web_detection

    if annotations.best_guess_labels:
        for label in annotations.best_guess_labels:
            print('\nBest guess label: {}'.format(label.label))

    if annotations.pages_with_matching_images:
        print('\n{} Pages with matching images found:'.format(
            len(annotations.pages_with_matching_images)))

        for page in annotations.pages_with_matching_images:
            print('\n\tPage url   : {}'.format(page.url))

            if page.full_matching_images:
                print('\t{} Full Matches found: '.format(
                       len(page.full_matching_images)))

                for image in page.full_matching_images:
                    print('\t\tImage url  : {}'.format(image.url))

            if page.partial_matching_images:
                print('\t{} Partial Matches found: '.format(
                       len(page.partial_matching_images)))

                for image in page.partial_matching_images:
                    print('\t\tImage url  : {}'.format(image.url))

    if annotations.web_entities:
        print('\n{} Web entities found: '.format(
            len(annotations.web_entities)))

        for entity in annotations.web_entities:
            print('\n\tScore      : {}'.format(entity.score))
            print(u'\tDescription: {}'.format(entity.description))

    if annotations.visually_similar_images:
        print('\n{} visually similar images found:\n'.format(
            len(annotations.visually_similar_images)))

        for image in annotations.visually_similar_images:
            print('\tImage url    : {}'.format(image.url))

Ruby

Before trying this sample, follow the Ruby setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Ruby API reference documentation .

# project_id = "Your Google Cloud project ID"
# image_path = "Google Cloud Storage URI, eg. 'gs://my-bucket/image.png'"

require "google/cloud/vision"

vision = Google::Cloud::Vision.new project: project_id
image  = vision.image image_path

web = image.web

web.entities.each do |entity|
  entity.description
end

web.full_matching_images.each do |image|
  puts image.url
end

Geographic metadata

The Vision API can access geotag metadata in your image files to return more relevant web entities and pages. To allow geotag usage, specify "include_geo_results": true in your request.

Protocol

This code uses a sample image stored in Google Cloud Storage. You can execute the code using this sample image, provide your own, or modify the code to accept an inline image (see the web detection samples page.)

Try setting includeGeoResults to false to test the impact of geographic hints on the results.

Refer to the images:annotate API endpoint for complete details.

To perform web entities detection, make a POST request and provide the appropriate request body:

POST https://vision.googleapis.com/v1/images:annotate?key=YOUR_API_KEY
{
  "requests": [
    {
      "features": [
        {
          "type": "WEB_DETECTION"
        }
      ],
      "image": {
        "source": {
          "gcsImageUri": "gs://bucket-name-123/geotagged.jpg"
        }
      },
      "imageContext": {
        "webDetectionParams": {
          "includeGeoResults": true
          }
        }
    }
  ]
}

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format:

{
  "responses": [
    {
      "webDetection": {
        "webEntities": [
          {
            "entityId": "/m/040sd3",
            "score": 40.5952,
            "description": "Luna Park Sydney"
          },
          {
            "entityId": "/m/0701q",
            "score": 22.4608,
            "description": "Sydney Harbour Bridge"
          },
          {
            "entityId": "/m/0d6_f6",
            "score": 9.904,
            "description": "Sea Life Sydney Aquarium"
          },
          {
            "entityId": "/g/11bxfg6b1k",
            "score": 8.384,
            "description": "Bradfield Park"
          },
          {
            "entityId": "/m/02q0lr",
            "score": 5.5,
            "description": "The Rocks"
          },
          ...
        ],
        "partialMatchingImages": [
          ...
        ],
        "pagesWithMatchingImages": [
          ...
        ],
        "visuallySimilarImages": [
          ...
        ],
        "bestGuessLabels": [
          {
            "label": "landmark"
          }
        ]
      }
    }
  ]
}

Go

Before trying this sample, follow the Go setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Go API reference documentation .

// detectWebGeo detects geographic metadata from the Vision API for an image at the given file path.
func detectWebGeo(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}

	f, err := os.Open(file)
	if err != nil {
		return err
	}
	defer f.Close()

	image, err := vision.NewImageFromReader(f)
	if err != nil {
		return err
	}
	imageContext := &visionpb.ImageContext{
		WebDetectionParams: &visionpb.WebDetectionParams{
			IncludeGeoResults: true,
		},
	}
	web, err := client.DetectWeb(ctx, image, imageContext)
	if err != nil {
		return err
	}

	if len(web.WebEntities) != 0 {
		fmt.Fprintln(w, "Entities:")
		fmt.Fprintln(w, "\tEntity\t\tScore\tDescription")
		for _, entity := range web.WebEntities {
			fmt.Fprintf(w, "\t%-14s\t%-2.4f\t%s\n", entity.EntityId, entity.Score, entity.Description)
		}
	}

	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Java API reference documentation .

/**
 * Find web entities given a local image.
 * @param filePath The path of the image to detect.
 * @param out A {@link PrintStream} to write the results to.
 * @throws Exception on errors while closing the client.
 * @throws IOException on Input/Output errors.
 */
public static void detectWebEntitiesIncludeGeoResults(String filePath, PrintStream out) throws
    Exception, IOException {
  // Instantiates a client
  try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
    // Read in the local image
    ByteString contents = ByteString.readFrom(new FileInputStream(filePath));

    // Build the image
    Image image = Image.newBuilder().setContent(contents).build();

    // Enable `IncludeGeoResults`
    WebDetectionParams webDetectionParams = WebDetectionParams.newBuilder()
        .setIncludeGeoResults(true)
        .build();

    // Set the parameters for the image
    ImageContext imageContext = ImageContext.newBuilder()
        .setWebDetectionParams(webDetectionParams)
        .build();

    // Create the request with the image, imageContext, and the specified feature: web detection
    AnnotateImageRequest request = AnnotateImageRequest.newBuilder()
        .addFeatures(Feature.newBuilder().setType(Type.WEB_DETECTION))
        .setImage(image)
        .setImageContext(imageContext)
        .build();

    // Perform the request
    BatchAnnotateImagesResponse response = client.batchAnnotateImages(Arrays.asList(request));

    // Display the results
    response.getResponsesList().stream()
        .forEach(r -> r.getWebDetection().getWebEntitiesList().stream()
            .forEach(entity -> {
              out.format("Description: %s\n", entity.getDescription());
              out.format("Score: %f\n", entity.getScore());
            }));
  }
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Node.js API reference documentation .

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ImageAnnotatorClient();

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const fileName = 'Local image file, e.g. /path/to/image.png';

const request = {
  image: {
    source: {
      filename: fileName,
    },
  },
  imageContext: {
    webDetectionParams: {
      includeGeoResults: true,
    },
  },
};

// Detect similar images on the web to a local file
client
  .webDetection(request)
  .then(results => {
    const webDetection = results[0].webDetection;

    webDetection.webEntities.forEach(entity => {
      console.log(`Score: ${entity.score}`);
      console.log(`Description: ${entity.description}`);
    });
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

Before trying this sample, follow the PHP setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API PHP API reference documentation .

namespace Google\Cloud\Samples\Vision;

use Google\Cloud\Vision\V1\ImageAnnotatorClient;
use Google\Cloud\Vision\V1\ImageContext;
use Google\Cloud\Vision\V1\WebDetectionParams;

// $path = 'path/to/your/image.jpg'

/**
 * Detect web entities on an image and include the image's geo metadata
 * to improve the quality of the detection.
 */
function detect_web_with_geo_metadata($path)
{
    $imageAnnotator = new ImageAnnotatorClient();

    # enable include geo results
    $params = new WebDetectionParams();
    $params->setIncludeGeoResults(true);
    $imageContext = new ImageContext();
    $imageContext-> setWebDetectionParams($params);

    # annotate the image
    $image = file_get_contents($path);
    $response = $imageAnnotator->webDetection($image, ['imageContext' => $imageContext]);
    $web = $response->getWebDetection();

    if ($web->getWebEntities()) {
        printf('%d web entities found:' . PHP_EOL,
            count($web->getWebEntities()));
        foreach ($web->getWebEntities() as $entity) {
            printf('Description: %s ' . PHP_EOL, $entity->getDescription());
            printf('Score: %f' . PHP_EOL, $entity->getScore());
            print(PHP_EOL);
        }
    }

    $imageAnnotator->close();
}

Python

Before trying this sample, follow the Python setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Python API reference documentation .

def web_entities_include_geo_results(path):
    """Detects web annotations given an image, using the geotag metadata
    in the image to detect web entities."""
    client = vision.ImageAnnotatorClient()

    with io.open(path, 'rb') as image_file:
        content = image_file.read()

    image = vision.types.Image(content=content)

    web_detection_params = vision.types.WebDetectionParams(
        include_geo_results=True)
    image_context = vision.types.ImageContext(
        web_detection_params=web_detection_params)

    response = client.web_detection(image=image, image_context=image_context)

    for entity in response.web_detection.web_entities:
        print('\n\tScore      : {}'.format(entity.score))
        print(u'\tDescription: {}'.format(entity.description))

Try it

Try web entities detection below. You can use the image specified already (gs://bucket-name-123/geotagged.jpg) by clicking Execute, or you can specify your own image in its place.

Try repeating the request with includeGeoResults set to false.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Vision API Documentation
Need help? Visit our support page.