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
          },
        ]
      }
    }
  ]
}

C#

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// 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

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// 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.NewClient(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)
	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:")
		for _, entity := range web.WebEntities {
			fmt.Fprintf(w, "\t\t%-12s %s\n", entity.ID, entity.Description)
		}
	}

	return nil
}

Java

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

public static void detectWebDetections(String filePath, PrintStream out) throws 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);

  BatchAnnotateImagesResponse response =
      ImageAnnotatorClient.create().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());
    }
    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());
    }
  }
}

Node.js

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

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

// Instantiates a client
const vision = Vision();

// The path to the local image file, e.g. "/path/to/image.png"
// const fileName = 'my-file.jpg';

// Detect similar images on the web to a local file
vision.detectSimilar(fileName)
  .then((results) => {
    const webDetection = results[1].responses[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}`);
      });
    }
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

Python

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

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

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

    image = vision_client.image(content=content)

    notes = image.detect_web()

    if notes.pages_with_matching_images:
        print('\n{} Pages with matching images retrieved')

        for page in notes.pages_with_matching_images:
            print('Score : {}'.format(page.score))
            print('Url   : {}'.format(page.url))

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

        for image in notes.full_matching_images:
            print('Score:  {}'.format(image.score))
            print('Url  : {}'.format(image.url))

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

        for image in notes.partial_matching_images:
            print('Score: {}'.format(image.score))
            print('Url  : {}'.format(image.url))

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

        for entity in notes.web_entities:
            print('Score      : {}'.format(entity.score))
            print('Description: {}'.format(entity.description))

Ruby

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

# 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 Cloud 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
          },
        ]
      }
    }
  ]
}

C#

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// Specify a Google Cloud Storage uri for the image.
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

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// 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.NewClient(ctx)
	if err != nil {
		return err
	}

	image := vision.NewImageFromURI(file)
	web, err := client.DetectWeb(ctx, image)
	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:")
		for _, entity := range web.WebEntities {
			fmt.Fprintf(w, "\t\t%-12s %s\n", entity.ID, entity.Description)
		}
	}

	return nil
}

Java

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

public static void detectWebDetectionsGcs(String gcsPath, PrintStream out) throws 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);

  BatchAnnotateImagesResponse response =
      ImageAnnotatorClient.create().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());
    }
    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());
    }
  }
}

Node.js

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

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

// Instantiates clients
const storage = Storage();
const vision = Vision();

// The name of the bucket where the file resides, e.g. "my-bucket"
// const bucketName = 'my-bucket';

// The path to the file within the bucket, e.g. "path/to/image.png"
// const fileName = 'my-file.jpg';

// Detect similar images on the web to a remote file
vision.detectSimilar(storage.bucket(bucketName).file(fileName))
  .then((results) => {
    const webDetection = results[1].responses[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}`);
      });
    }
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

Python

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

def detect_web_uri(uri):
    """Detects web annotations in the file located in Google Cloud Storage."""
    vision_client = vision.Client()
    image = vision_client.image(source_uri=uri)

    notes = image.detect_web()

    if notes.pages_with_matching_images:
        print('\n{} Pages with matching images retrieved')

        for page in notes.pages_with_matching_images:
            print('Score : {}'.format(page.score))
            print('Url   : {}'.format(page.url))

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

        for image in notes.full_matching_images:
            print('Score:  {}'.format(image.score))
            print('Url  : {}'.format(image.url))

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

        for image in notes.partial_matching_images:
            print('Score: {}'.format(image.score))
            print('Url  : {}'.format(image.url))

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

        for entity in notes.web_entities:
            print('Score      : {}'.format(entity.score))
            print('Description: {}'.format(entity.description))

Ruby

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

# 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

Send feedback about...

Google Cloud Vision API Documentation