Reporting usage with labels (Advanced)

The Translation API supports adding user-defined labels (key-value pairs) to TranslateText, BatchTranslateText and DetectLanguage requests. Information about a request's usage is forwarded to the billing system where you can break down your billing charges by filtering by label.

Use case

An important use case for labels involves customers who provide translation services to many clients. A single project can be used for multiple clients. For billing purposes it's important to associate specific requests with their respective clients. That's where labels come in. When making a call on behalf of a client, you label the request with a client specific label. These labels are then available for filtering purposes in the Reports section of the Google Cloud Platform.

Requirements for labels

The labels applied to a request must meet the following requirements:

  • Each request can have multiple labels, up to a maximum of 64.
  • Each label must be a key-value pair.
  • Keys have a minimum length of 1 character and a maximum length of 63 characters, and cannot be empty. Values can be empty, and have a maximum length of 63 characters.
  • Keys and values contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed.
  • The key portion of a label must be unique within a single request (for example, {'country':'india'} is fine, but {'country':'india','country':'sweden'} is not allowed).
  • Keys must start with a lowercase letter or international character.

Projects charged

In Translation API, labels are often used to organize fees for a given billing account. Fees are associated with the billing account of the project that contains the request. When a custom or general model is used, pricing is checked against the project ID associated with the model.

For billing purposes, all billable requests can have labels of their own. These billable requests include batch translation, detect language, and translate text.

Creating and managing labels using the Translation API

Use the Translation API to add labels to a request.

REST & CMD LINE

In the following example, the labels {'country':'russia'},{'env':'test'} are added to the translateText request.

Before using any of the request data below, make the following replacements:

  • project-number-or-id: your GCP project number or ID

HTTP method and URL:

POST https://translation.googleapis.com/v3/projects/project-number-or-id:translateText

Request JSON body:

{
  source_language_code: 'en',
  target_language_code: 'ru',
  contents: 'Dr. Watson, come here!',
  labels: {'country':'russia','env':'test'}
}

To send your request, choose one of these options:

curl

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://translation.googleapis.com/v3/projects/project-number-or-id:translateText

PowerShell

Save the request body in a file called request.json, and execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://translation.googleapis.com/v3/projects/project-number-or-id:translateText " | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "translations": [
    {
      "translatedText": "Доктор Ватсон, иди сюда!"
    }
  ]
}

Pricing report

Go to the Google Cloud Platform(GCP) billing console Reports view to use these labels as filters for request usage.

  1. From the dashboard, click the hamburger icon on the upper left-hand side and select "Billing" from the drop-down. If you have multiple billing accounts a page appears that asks you to make a selection. Click "Go to linked billing account."
  2. From the Billing page, select Reports in the left-hand nav.
  3. Use the filters in the right-hand nav to check usage of requests.
Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Translation
Need help? Visit our support page.