Module: Google::Cloud::Language

Defined in:: lib/google/cloud/language.rb,
lib/google/cloud/language/project.rb,
lib/google/cloud/language/service.rb,
lib/google/cloud/language/version.rb,
lib/google/cloud/language/document.rb,
lib/google/cloud/language/annotation.rb,
lib/google/cloud/language/credentials.rb

Overview

Google Cloud Natural Language API

Google Cloud Natural Language API reveals the structure and meaning of text by offering powerful machine learning models in an easy to use REST API. You can use it to extract information about people, places, events and much more, mentioned in text documents, news articles or blog posts. You can use it to understand sentiment about your product on social media or parse intent from customer conversations happening in a call center or a messaging app. You can analyze text uploaded in your request or integrate with your document storage on Google Cloud Storage. Combine the API with the Google Cloud Speech API and extract insights from audio conversations. Use with Vision API OCR to understand scanned documents. Extract entities and understand sentiments in multiple languages by translating text first with Translate API.

The Google Cloud Natural Language API is currently a beta release, and might be changed in backward-incompatible ways. It is not subject to any SLA or deprecation policy and is not intended for real-time usage in critical applications.

For more information about Cloud Natural Language API, read the Google Cloud Natural Language API Documentation.

The goal of google-cloud is to provide an API that is comfortable to Rubyists. Authentication is handled by #language. You can provide the project and credential information to connect to the Cloud Natural Language API, or if you are running on Google Compute Engine this configuration is taken care of for you. You can read more about the options for connecting in the Authentication Guide.

Creating documents

Cloud Natural Language API supports UTF-8, UTF-16, and UTF-32 encodings. (Ruby uses UTF-8 natively, which is the default sent to the API, so unless you're working with text processed in different platform, you should not need to set the encoding type.) Be aware that only English, Spanish, and Japanese language content are supported, and sentiment analysis only supports English text.

Use Project#document to create documents for the Cloud Natural Language service. You can provide text or HTML content as a string:

require "google/cloud"

gcloud = Google::Cloud.new
language = gcloud.language

document = language.document "It was the best of times, it was..."

Or, you can pass a Google Cloud Storage URI for a text or HTML file:

require "google/cloud"

gcloud = Google::Cloud.new
language = gcloud.language

document = language.document "gs://bucket-name/path/to/document"

Or, you can initialize it with a Google Cloud Storage File object:

require "google/cloud"

gcloud = Google::Cloud.new
storage = gcloud.storage

bucket = storage.bucket "bucket-name"
file = bucket.file "path/to/document"

language = gcloud.language

document = language.document file

You can specify the format and language of the content:

require "google/cloud"

gcloud = Google::Cloud.new
language = gcloud.language

document = language.document "<p>El viejo y el mar</p>",
                             format: :html, language: "es"

Creating a Document instance does not perform an API request.

Annotating documents

The instance methods on Document invoke Cloud Natural Language's detection features individually. Each method call makes an API request. If you want to run multiple features in a single request, see the examples for Document#annotate, below. Calling annotate with no arguments will perform all analysis features. Each feature is priced separately. See Pricing for details.

Sentiment analysis inspects the given text and identifies the prevailing emotional opinion within the text, especially to determine a writer's attitude as positive, negative, or neutral. Sentiment analysis can be performed with the Document#sentiment method. Currently, only English is supported for sentiment analysis.

require "google/cloud"

gcloud = Google::Cloud.new
language = gcloud.language

content = "Darth Vader is the best villain in Star Wars."
document = language.document content
sentiment = document.sentiment # API call

sentiment.polarity #=> 1.0
sentiment.magnitude #=> 0.8999999761581421

Entity analysis inspects the given text for known entities (proper nouns such as public figures, landmarks, etc.) and returns information about those entities. Entity analysis can be performed with the Document#entities method.

require "google/cloud"

gcloud = Google::Cloud.new
language = gcloud.language

content = "Darth Vader is the best villain in Star Wars."
document = language.document content
entities = document.entities # API call

entities.count #=> 2
entities.first.name #=> "Darth Vader"
entities.first.type #=> :PERSON
entities.first.name #=> "Star Wars"
entities.first.type #=> :WORK_OF_ART

Syntactic analysis extracts linguistic information, breaking up the given text into a series of sentences and tokens (generally, word boundaries), providing further analysis on those tokens. Syntactic analysis can be performed with the Document#syntax method.

require "google/cloud"

gcloud = Google::Cloud.new
language = gcloud.language

content = "Darth Vader is the best villain in Star Wars."
document = language.document content
syntax = document.syntax # API call

syntax.sentences.count #=> 1
syntax.tokens.count #=> 10

To run multiple features on a document in a single request, pass the flag for each desired feature to Document#annotate:

require "google/cloud"

gcloud = Google::Cloud.new
language = gcloud.language

content = "Darth Vader is the best villain in Star Wars."
document = language.document content
annotation = document.annotate entities: true, text: true

annotation.sentiment #=> nil
annotation.entities.count #=> 2
annotation.sentences.count #=> 1
annotation.tokens.count #=> 10

Or, simply call Document#annotate with no arguments to process the document with all features:

require "google/cloud"

gcloud = Google::Cloud.new
language = gcloud.language

content = "Darth Vader is the best villain in Star Wars."
document = language.document content
annotation = document.annotate

annotation.sentiment.polarity #=> 1.0
annotation.sentiment.magnitude #=> 0.8999999761581421
annotation.entities.count #=> 2
annotation.sentences.count #=> 1
annotation.tokens.count #=> 10

Defined Under Namespace

Classes: Annotation, Document, Project

Constant Summary collapse

VERSION =

"0.20.1"