Audience

This tutorial is designed to let you quickly start exploringand developing applications with the Google Cloud Natural Language API. It isdesigned for people familiar with basic programming, though even without muchprogramming knowledge, you should be able to follow along. Having walked throughthis tutorial, you should be able to use theReference documentation to create your ownbasic applications.

This tutorial steps through a Natural Language API application using Pythoncode. The purpose here is not to explain the Python client libraries, but toexplain how to make calls to the Natural Language API. Applications in Javaand Node.js are essentially similar. Consult the Natural Language APISamples for samples in other languages (including this sample withinthe tutorial).

Prerequisites

This tutorial has several prerequisites:

• You have a Google Cloud account. If you're new to the platform,create an account to evaluate how our products perform inreal-world scenarios. New customers also get $300 in free credits to run,test, and deploy workloads.
• You'veset up a Cloud Natural Language API project in the Google Cloud console.
• You've set up your environment usingApplication Default Credentials.
• You have basic familiarity withPython programming.
• You have set up your Python development environment. It is recommended that you havethe latest version of Python,pip, andvirtualenv installed on your system.For instructions, see thePython Development Environment Setup Guidefor Google Cloud Platform.
• You've installed theGoogle Cloud Client Library for Python

Analyzing document sentiment

This tutorial walks you through a basic Natural Language API application, usingananalyzeSentiment request, which performs sentiment analysis on text.Sentiment analysis attempts to determine the overall attitude (positive ornegative) and is represented by numericalscore andmagnitude values.(For more information on these concepts, consultNatural Language Basics.)

We'll show the entire code first. (Note that we have removed most comments fromthis code in order to show you how brief it is. We'll provide more comments aswe walk through the code.)

"""Demonstrates how to make a simple call to the Natural Language API."""importargparsefromgoogle.cloudimportlanguage_v1defprint_result(annotations):score=annotations.document_sentiment.scoremagnitude=annotations.document_sentiment.magnitudeforindex,sentenceinenumerate(annotations.sentences):sentence_sentiment=sentence.sentiment.scoreprint(f"Sentence{index} has a sentiment score of{sentence_sentiment}")print(f"Overall Sentiment: score of{score} with magnitude of{magnitude}")return0defanalyze(movie_review_filename):"""Run a sentiment analysis request on text within a passed filename."""client=language_v1.LanguageServiceClient()withopen(movie_review_filename)asreview_file:# Instantiates a plain text document.content=review_file.read()document=language_v1.Document(content=content,type_=language_v1.Document.Type.PLAIN_TEXT)annotations=client.analyze_sentiment(request={"document":document})# Print the resultsprint_result(annotations)if__name__=="__main__":parser=argparse.ArgumentParser(description=__doc__,formatter_class=argparse.RawDescriptionHelpFormatter)parser.add_argument("movie_review_filename",help="The filename of the movie review you'd like to analyze.",)args=parser.parse_args()analyze(args.movie_review_filename)

This simple application performs the following tasks:

• Imports the libraries necessary to run the application
• Takes a text file and passes it to themain() function
• Reads the text file and makes a request to the service
• Parses the response from the service and displays it to the user

We'll go over these steps in more detail below.

Importing libraries

importargparsefromgoogle.cloudimportlanguage_v1

We importargparse, a standard library, to allow the application to acceptinput filenames as arguments.

For using the Cloud Natural Language API, we'll also want to import thelanguage module from thegoogle-cloud-language library. Thetypes modulecontains classes that are required for creating requests.

Running your application

if__name__=="__main__":parser=argparse.ArgumentParser(description=__doc__,formatter_class=argparse.RawDescriptionHelpFormatter)parser.add_argument("movie_review_filename",help="The filename of the movie review you'd like to analyze.",)args=parser.parse_args()analyze(args.movie_review_filename)

Here, we simply parse the passed argument for the text filename and pass it totheanalyze() function.

Authenticating to the API

Before communicating with the Natural Language API service, you need toauthenticate your service using previously acquired credentials. Within anapplication, the simplest way to obtain credentials is to useApplication Default Credentials (ADC). By default, ADC will attempt to obtain credentials from theGOOGLE_APPLICATION_CREDENTIALS environment file, which should be set to pointto your service account's JSON key file. (You should have set up your serviceaccount and environment to use ADC in theQuickstart. SeeSetting Up a Service Account for more information.)

The Google Cloud Client Library for Python automatically uses the applicationdefault credentials.

Making the request

Now that our Natural Language API service is ready, we can access the service by calling theanalyze_sentiment method of theLanguageServiceClient instance.

The client library encapsulates the details for requests and responses to the API. See theNatural Language API Reference for completeinformation on the specific structure of such a request.

defanalyze(movie_review_filename):"""Run a sentiment analysis request on text within a passed filename."""client=language_v1.LanguageServiceClient()withopen(movie_review_filename)asreview_file:# Instantiates a plain text document.content=review_file.read()document=language_v1.Document(content=content,type_=language_v1.Document.Type.PLAIN_TEXT)annotations=client.analyze_sentiment(request={"document":document})# Print the resultsprint_result(annotations)

This code snippet performs the following tasks:

1. Instantiates aLanguageServiceClient instance as the client.
2. Reads the filename containing the text data into a variable.
3. Instantiates aDocument object with the contents of the file.
4. Calls the client'sanalyze_sentiment method.

Parsing the response

defprint_result(annotations):score=annotations.document_sentiment.scoremagnitude=annotations.document_sentiment.magnitudeforindex,sentenceinenumerate(annotations.sentences):sentence_sentiment=sentence.sentiment.scoreprint(f"Sentence{index} has a sentiment score of{sentence_sentiment}")print(f"Overall Sentiment: score of{score} with magnitude of{magnitude}")return0

We walk through the response to extract the sentimentscore values for eachsentence, and the overallscore andmagnitude values for the entire review,and display those to the user.

Run the sample

To run our sample, we'll test it on a set of (fake) movie reviews for themovie "Bladerunner."

1. Download the samples from Google Cloud Storage:

   gcloud storage cp gs://cloud-samples-tests/natural-language/sentiment-samples.tgz .

   To install the latest version of Google Cloud CLI, refer togcloud CLI documentation.

2. Unzip those samples, which will create a "reviews" folder:

   gunzip sentiment-samples.tgztar -xvf sentiment-samples.tar

3. Run our sentiment analysis on one of the specified files:

   python sentiment_analysis.py reviews/bladerunner-pos.txtSentence 0 has a sentiment score of 0.8Sentence 1 has a sentiment score of 0.9Sentence 2 has a sentiment score of 0.8Sentence 3 has a sentiment score of 0.2Sentence 4 has a sentiment score of 0.1Sentence 5 has a sentiment score of 0.4Sentence 6 has a sentiment score of 0.3Sentence 7 has a sentiment score of 0.4Sentence 8 has a sentiment score of 0.2Sentence 9 has a sentiment score of 0.9Overall Sentiment: score of 0.5 with magnitude of 5.5

The above example would indicate a review that was relatively positive(score of0.5), and relatively emotional (magnitude of5.5).

Running analysis on the other examples should produce values similar to thoseshown below:

python sentiment_analysis.py reviews/bladerunner-neg.txt...Overall Sentiment: score of -0.6 with magnitude of 3.3python sentiment_analysis.py reviews/bladerunner-mixed.txt...Overall Sentiment: score of 0 with magnitude of 4.7python sentiment_analysis.py reviews/bladerunner-neutral.txt...Overall Sentiment: score of -0.1 with magnitude of 1.8

Note that the magnitudes are all similar (indicating a relative equal amountof emotionally significant sentiment) except for the "neutral" case, whichindicates a review with not very much emotional sentiment, either positive ornegative. (For more informationon sentiment scores and magnitude, and how to interpret these values, seeInterpreting Sentiment Analysis Values.)

If you wish to explore sentiment analysis with more data, Stanford provides adataset ofIMDB movie reviews. Toretrieve these movie reviews:

1. Download theLarge Movie Reviewdataset.
2. Unzip the file into your working directory. The movie reviews are dividedintopos andneg directories withintrain andtest data directories,with each text file containing one movie review.
3. Run thesentiment_analysis.py tool on any of the movie review text files.

Congratulations! You've performed your first inference tasks using the GoogleCloud Natural Language API!