Quickstart

Installing the Google Cloud SDK

The Google Natural Language API makes use of the gcloud command line tool, which is distributed within the Google Cloud Platform Cloud SDK. Follow the instructions on that page to install and set up the Cloud SDK.

Note: if you are using a Google Compute Engine VM, you should already have the Cloud SDK preinstalled on that image.

Set up your project

If you haven't already done so:

  1. Sign in to your Google account.

    If you don't already have one, sign up for a new account.

  2. In the Cloud Platform Console, go to the Projects page and select or create a new project.

    Go to the Projects page

  3. Enable billing for your project.

    Enable billing

  4. Enable the Cloud Natural Language API.

    Enable the API

  5. After enabling the Google Cloud Natural Language API, click the Go to Credentials button to set up your Cloud Natural Language API credentials:

  6. See the authentication guide for information on how to authenticate to the Cloud Natural Language API service from your code. Following those steps, you should obtain both a service account key file (in JSON) and a GOOGLE_APPLICATION_CREDENTIALS environment variable that will allow you to authenticate to the Natural Language API in this Quickstart.

Make an entity analysis request

  1. Create a JSON request file with the following text, and save it as an entity-request.json plain text file:

    {
      "document":{
        "type":"PLAIN_TEXT",
        "content":"Michelangelo Caravaggio, Italian painter, is known for
                  'The Calling of Saint Matthew'."
      },
      "encodingType":"UTF8"
    }
      
  2. Authenticate to your service account, passing the location of your service account key file:

    gcloud auth activate-service-account --key-file=service-account-key-file
      
  3. If you have not already done so, set the Application Default Credentials (ADC) GOOGLE_APPLICATION_CREDENTIALS environment variable:

    export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json
      
  4. Obtain an authentication token using your service account:

    gcloud auth application-default print-access-token
    access_token
      
  5. Use curl to make a documents:analyzeEntities request, passing it the access token you printed, and the filename of the entity request:

    curl -s -k -H "Content-Type: application/json" \
        -H "Authorization: Bearer access_token" \
        https://language.googleapis.com/v1/documents:analyzeEntities \
        -d @entity-request.json
      

    Note that to pass a filename to curl you use the -d option (for "data") and precede the filename with an @ sign. This file should be in the same directory in which you execute the curl command.

    You should see a response similar to the following:

    {
      "entities": [
        {
          "name": "Michelangelo Caravaggio",
          "type": "PERSON",
          "metadata": {
            "mid": "/m/020bg",
            "wikipedia_url": "http://en.wikipedia.org/wiki/Caravaggio"
          },
          "salience": 0.81869245,
          "mentions": [
            {
              "text": {
                "content": "Michelangelo Caravaggio",
                "beginOffset": 0
              },
              "type": "PROPER"
            },
            {
              "text": {
                "content": "painter",
                "beginOffset": 33
              },
              "type": "COMMON"
            }
          ]
        },
        {
          "name": "Italian",
          "type": "LOCATION",
          "metadata": {
            "mid": "/m/03rjj",
            "wikipedia_url": "http://en.wikipedia.org/wiki/Italy"
          },
          "salience": 0.14450249,
          "mentions": [
            {
              "text": {
                "content": "Italian",
                "beginOffset": 25
              },
              "type": "PROPER"
            }
          ]
        },
        {
          "name": "The Calling of Saint Matthew",
          "type": "WORK_OF_ART",
          "metadata": {
            "mid": "/m/085_p7",
            "wikipedia_url": "http://en.wikipedia.org/wiki/The_Calling_of_St_Matthew_(Caravaggio)"
          },
          "salience": 0.036805071,
          "mentions": [
            {
              "text": {
                "content": "The Calling of Saint Matthew",
                "beginOffset": 56
              },
              "type": "PROPER"
            }
          ]
        }
      ],
      "language": "en"
    }
      

Congratulations! You've sent your first request to Cloud Natural Language API.

Clean up

To avoid unnecessary Google Cloud Platform charges, use the Cloud Platform Console to delete your project if you do not need it.

What's next

Send feedback about...

Google Cloud Natural Language API Documentation