Start with the big picture: what “natural language” means and what Google Cloud offers.

Natural language is the language people use every day, such as English, Hindi, Spanish or Japanese, as opposed to the strict, formal languages that computers use, such as programming languages. Computers find natural language hard because it is messy. The same idea can be said many ways, words have several meanings, and meaning often depends on context, tone and shared knowledge.

Natural Language Processing, usually shortened to NLP, is the branch of artificial intelligence that deals with this problem. NLP systems read text and produce useful structured facts from it, such as “this review is negative”, “this sentence mentions the city of Mumbai” or “this article is about sports”.

In Google Cloud, the core product with this name is the Cloud Natural Language API. An API (application programming interface) is a doorway that lets your program ask another service to do a job. You send the API some text, and it sends back a structured answer. You do not need to build, train or host any model yourself. Google has already trained the underlying models on huge amounts of text, and runs them for you as a managed service.

Google Cloud also offers newer generative AI models, such as the Gemini family, available through Vertex AI. These can also read and understand text, and they can write, summarize and answer questions. A big part of this guide explains how the classic language API and the newer generative models differ, and how to choose between them.

What the Natural Language API can tell you

• Sentiment: is the writer positive, negative or neutral?
• Entities: which people, places, organizations, products and other things are mentioned?
• Entity sentiment: how does the writer feel about each specific thing?
• Syntax: how are the words and sentences built grammatically?
• Content categories: what broad topic is the text about?
• Text moderation: does the text contain harmful or sensitive material?

Every good tool begins with a pain. Here are the pains of drowning in text.

Pain 1: Too much text, too few readers

A large company may receive tens of thousands of emails, chats and reviews daily. Reading them all by hand is impossible, so most are never read. Important complaints sit unnoticed, and good ideas are lost.

Pain 2: Text is unstructured

Databases love tidy tables: numbers, dates and categories. Text is the opposite. It is unstructured data, which means it has no fixed columns or rows. You cannot add up or sort a pile of paragraphs. NLP turns text into structured facts, such as a sentiment score or a list of mentioned products, that you can count, chart and filter.

Pain 3: Slow and inconsistent human judgement

Two people reading the same review may disagree on whether it is angry or merely disappointed. A tired reader at the end of a shift may judge differently than a fresh one. Software applies the same method to every message every time, which gives consistent, comparable results.

Pain 4: Delay

A furious customer message that sits in an inbox for two days becomes a lost customer. Automatic reading lets you flag urgent or angry messages within seconds, and route them to the right team.

Pain 5: Safety and trust

Websites and apps that allow user comments must prevent abuse, hate and dangerous content. Reviewing every post by hand does not scale. Automated checks can catch the worst content quickly and send doubtful cases to human moderators.

Pain 6: Building language models is hard

Training a language model needs huge amounts of data, powerful computers and specialist skills. Most companies cannot afford to do this for every task. Using a ready-made, managed service lets small teams add language abilities in days instead of years.

Eight ideas explain most of what you will meet in the documentation.

Handy words

See the whole toolbox at a glance and how your application sits around it.

The Cloud Natural Language API is a managed service that lives on Google’s side. Your application sends text over the internet, using a secure connection, and receives a structured response. Inside the service, several different models specialize in different jobs. You choose which jobs to run for each document. You can ask for one job or several together.

flowchart TB
  Doc["Your Text Document"] --> API["Cloud Natural Language API"]
  API --> S["Sentiment Analysis"]
  API --> E["Entity Analysis"]
  API --> ES["Entity Sentiment Analysis"]
  API --> SY["Syntax Analysis"]
  API --> CC["Content Classification"]
  API --> TM["Text Moderation"]
  S --> R["Structured Response"]
  E --> R
  ES --> R
  SY --> R
  CC --> R
  TM --> R
  R --> App["Your Application, Database or Dashboard"]
    

Walking through the picture

Your document goes in at the top. The API passes it to whichever analysis features you requested. Each feature produces its own part of the answer, and the API combines them into one response. Your application then stores the results, shows them to users or uses them to trigger actions, such as alerting a support manager.

The main components

• Your application or pipeline: the code that collects text and calls the API. It might run on Cloud Run, Cloud Run functions, Compute Engine or Google Kubernetes Engine.
• Client libraries: ready-made helpers for popular programming languages that handle the connection and the format of requests.
• Authentication: service accounts and Identity and Access Management (IAM) decide which programs may call the API.
• The Natural Language API: Google’s managed service holding the models and applying them.
• Storage and analytics: places where you keep results, such as BigQuery or Cloud Storage, and tools to chart them.
• Related Google Cloud services: Speech-to-Text for audio, Translation for other languages, Document AI for scanned papers, and Vertex AI for generative models.

Follow one review from your app, through the service and back again.

sequenceDiagram
  participant App as Your Application
  participant Auth as Google Identity
  participant NL as Natural Language API
  participant Model as Language Models
  App->>Auth: Prove who the application is
  Auth-->>App: Short-lived access credential
  App->>NL: Send document and list of features
  NL->>Model: Break text into sentences and tokens
  Model-->>NL: Sentiment, entities and other results
  NL-->>App: Structured response with scores and labels
  App->>App: Store results or trigger an action
    

Step 1: Prove who you are

Your application must be allowed to use the API. In production, it runs as a service account, which is a special identity for programs, and receives a short-lived credential. This avoids storing passwords in code.

Step 2: Build the request

The request says what the document is (its text, whether it is plain text or HTML, and optionally its language) and which features you want. If you do not name a language, the service tries to detect it. You may also choose how character positions are counted in the answer, which matters if your program must point to exact spots in the text.

Step 3: Analyze

The service first splits your text into sentences and words, which is called tokenization. Then the language models examine them. Different models work on different tasks: one judges feelings, another recognizes named things, another maps grammar, another assigns topics, and so on.

Step 4: Read the response

The response is structured data, usually JSON, which is a simple text format for lists and labeled values. It might say: overall sentiment score is minus 0.6; the entity “Delhi Airport” appears twice and is a location; the category is “Travel”. Your code reads these values and decides what to do.

Step 5: Act on it

Your application saves the results in a database, updates a dashboard, tags a support ticket, or flags a comment for review. The analysis itself changes nothing. Your own logic turns insight into action.

A piece of text is collected, cleaned, analyzed, stored and used. Here is that life story.

Batch versus real time

Some uses need an answer within a second, such as checking a comment before it is posted. Others can take their time, such as analyzing last month’s reviews overnight. Real-time uses call the API directly from an application. Batch uses read large sets of stored text and send them through in controlled groups. Choosing between the two shapes your design, your costs and your waiting times.

Understanding the two numbers that describe feeling: score and magnitude.

Sentiment analysis estimates the emotional attitude behind a piece of text. The API reports two numbers, and understanding both is the key to using them well.

Score: which way?

The score ranges from minus one to plus one. Values near minus one mean negative feelings, values near plus one mean positive feelings, and values near zero mean neutral or mixed feelings.

Magnitude: how strong?

The magnitude says how much emotional content there is overall, regardless of whether it is positive or negative. It starts at zero and has no fixed upper limit. Longer text with lots of emotion has higher magnitude, because the amounts add up.

Why you need both

A score near zero can mean two very different things. A short, factual note (“The package arrived on Tuesday”) has score near zero and low magnitude. A long message full of strong praise and strong anger can also average to a score near zero, but with high magnitude. Looking at the score alone would treat them the same. The table shows the idea.

Document level and sentence level

The API gives one overall result for the whole document, and also a result for each sentence. Sentence results are very helpful for long reviews: you can find exactly which sentences are negative and read them first.

Setting thresholds

Most businesses turn scores into simple rules, such as “if score is below minus 0.5, flag for the support manager”. There is no universal best cutoff. Check a sample of real messages from your own business, compare the scores with what a human thinks, and tune the cutoff to match your needs.

Finding the people, places, products and things inside the text, and how the writer feels about each.

What an entity is

An entity is a specific “thing” that the text talks about. Entity analysis finds these things, labels their type, and judges how important each is. Common types include:

• Person: names of people.
• Location: cities, countries, landmarks and addresses.
• Organization: companies, schools and agencies.
• Event: festivals, wars, sports matches and similar.
• Work of art: books, songs and films.
• Consumer good: products and brands.
• Other types: such as phone numbers, addresses, dates, numbers and prices, with an “other” group for things that fit nowhere else.

Salience: what is the text really about?

Every entity gets a salience score, which tells you how central it is to the text. In a news story about a company launching a phone, the company and phone have high salience, while a passing mention of a city has low salience. Salience helps you keep only the main subjects and ignore the background noise.

Mentions and extra information

The same entity can be mentioned in different ways, such as “Google”, “the company” and “it”. The API groups these mentions together as one entity. For well-known entities it can also provide extra information, such as a link to a public encyclopedia page or an identifier from a large knowledge database. This helps you tell the difference between, for example, the animal “jaguar” and the car brand.

Entity sentiment: feelings about each thing

A review can be positive overall but negative about one thing: “The hotel room was lovely but the breakfast was awful.” Overall sentiment may be near zero. Entity sentiment analysis gives a separate sentiment score and magnitude for each entity, so you learn that “room” is positive and “breakfast” is negative. This is much more useful for improving a product than a single overall score.

How businesses use entities

• Product feedback: count which features customers mention most and how they feel about each.
• News and media: tag articles with the people, places and organizations they discuss, to enable search and recommendations.
• Legal and compliance: find names, organizations and dates inside long documents.
• Customer support: automatically detect product names and route the ticket to the correct team.

Three more features: how sentences are built, what topic they cover, and whether they are safe.

Syntax analysis

Syntax is the grammar of language. Syntax analysis breaks text into sentences and tokens, and for each token reports its lemma (base form), its part of speech and its place in a dependency structure, which shows which words depend on which others. For example, in “The quick fox jumped”, the word “jumped” is the main verb, “fox” is the subject, and “quick” describes “fox”.

Most business users do not need syntax directly. It is valuable for people who build their own language tools, such as grammar helpers, search engines that match word forms, and systems that extract “who did what to whom”.

Content classification

Content classification assigns the text to categories from a large built-in list organized like a tree, such as “Arts and Entertainment, Music” or “Finance, Banking”. Each category comes with a confidence score, and a text may match more than one. This is a fast way to sort big collections of articles, web pages or posts by subject. The text needs to be long enough to carry a topic, so very short snippets work poorly. The supported languages differ between versions of the classification model, so check the current list.

Text moderation

Text moderation checks text against a list of sensitive or harmful topics and gives each a confidence score. These typically include toxic content, insults, profanity, sexual content, violence and similar areas, and also topics that are not necessarily harmful but may need care, such as politics, health, finance or legal matter, depending on the model. You decide what to do with the scores: block the comment, hide it until reviewed, or just log it.

What kind of text the service accepts, and the boundaries you must respect.

Languages

The API supports many languages, but not every feature supports every language equally. Sentiment and entity analysis cover a wide range, while some features such as classification and moderation may support fewer. If you do not specify a language, the service tries to detect it. For a mix of languages, you can either detect the language first and send text accordingly, or translate to a main language using the Translation service before analysis, accepting some loss of nuance. Always check the current supported language table for each feature.

Input formats

• Plain text: the usual choice for reviews, messages and transcripts.
• HTML: useful when the text comes from a web page, as the service can ignore the tags. Cleaning the page yourself first often gives the best results.
• Files in Cloud Storage: you can point the service at a text file stored in a Cloud Storage bucket instead of sending the text inside the request.

Size and rate limits

Each request has a maximum size, and there are quotas on how many requests you can send per minute and per day. Defaults exist and can often be raised by request. Very long documents may need to be split into sections. Check current quotas, because they change, and design your system so that hitting a limit leads to a polite wait and retry, not a crash.

Choosing text encoding

When the API tells you where in the text something was found, it uses character positions. Different programming languages count positions differently, particularly with emoji and special characters. The request lets you pick the encoding type so that the positions you receive match how your own program counts them.

Working with other kinds of input

The Natural Language API reads text only. For other sources, you first convert them into text:

• Phone calls and voice notes: use Speech-to-Text to create a transcript.
• Scanned letters, forms and PDFs: use Document AI or optical character recognition to extract the text.
• Text in images: use Vision AI features to read the text.
• Other languages: use Cloud Translation, if you prefer to analyze in one language.

The most important design choice: which tool should do the reading?

Google Cloud offers several ways to understand text, and each fits different needs. It helps to think of three choices.

Choice 1: The Natural Language API

This is the ready-made service with fixed features: sentiment, entities, syntax, categories and moderation. It is fast, simple, predictable and priced per amount of text. The answers always come in the same fixed format. The limit is that you cannot ask it new kinds of questions, and you cannot teach it your own labels.

Choice 2: Generative AI models in Vertex AI

Large language models, such as the Gemini family available in Vertex AI, can follow written instructions. You can ask them to summarize a long email, extract specific fields like order number and complaint type, rate urgency on your own scale, translate tone, write a reply, or answer questions about a document. They are very flexible and need no training data, only a good prompt, and sometimes a few examples. The trade-offs are higher cost per request, slower responses than a simple API, and answers that can vary and sometimes be wrong or invented. They need careful testing and guard rails.

Choice 3: A custom-trained model

If you have thousands of labeled examples and a very specific task, such as sorting tickets into your company’s own forty categories, you can train or tune a model on your own data using Vertex AI tools. This can deliver high accuracy for your exact task and low cost per prediction once built, but it takes data, time and skill to build and maintain. Google’s older, separate AutoML text products have been folded into Vertex AI and parts have been retired, so check the current guidance for training or tuning options.

flowchart TD
  Start["What Do You Need From the Text?"] --> Q1{"Is it a standard task like sentiment, entities, topic or moderation?"}
  Q1 -->|"Yes"| Q2{"Need very high volume with low cost and steady output?"}
  Q2 -->|"Yes"| A["Use the Natural Language API"]
  Q2 -->|"No - need custom wording"| B["Consider Generative Models in Vertex AI"]
  Q1 -->|"No - custom labels or fields"| Q3{"Do you have many labeled examples and a stable task?"}
  Q3 -->|"Yes"| C["Train or Tune a Custom Model in Vertex AI"]
  Q3 -->|"No"| D["Use Generative Models with Clear Prompts and Examples"]
    

Side-by-side comparison

How the pieces connect in a real system that handles thousands of messages.

A pipeline is a chain of steps that data flows through automatically. Here is a typical pipeline for analyzing customer feedback. It uses services you may already know from Google Cloud.

flowchart LR
  Src["Feedback Sources - App Reviews, Emails, Chats"] --> Topic["Pub/Sub Topic"]
  Topic --> Worker["Cloud Run Worker Service"]
  Worker --> Clean["Clean and Mask Sensitive Details"]
  Clean --> NL["Natural Language API"]
  NL --> Worker
  Worker --> BQ["BigQuery Results Table"]
  Worker --> Alert["Alert for Very Negative Messages"]
  BQ --> Dash["Dashboard for Business Teams"]
  Worker --> Dead["Dead-Letter Topic for Failures"]
    

Walking through the pipeline

• Collect: every new piece of feedback is published as a message to a Pub/Sub topic. Pub/Sub acts as a buffer that absorbs sudden bursts.
• Process: a Cloud Run service receives messages, cleans the text, and masks sensitive items such as card numbers or phone numbers. The Sensitive Data Protection service can help find and mask these.
• Analyze: the worker sends the cleaned text to the Natural Language API, asking for sentiment, entities and categories in a single combined request.
• Store: results go into BigQuery, linked to the original message ID, so teams can query and chart them.
• Alert: very negative or flagged messages trigger a notification to a support team.
• Recover: messages that keep failing go to a dead-letter topic where engineers can inspect them.

Other ways to connect

• Dataflow: for big streaming or batch jobs, a Dataflow pipeline can read from storage or Pub/Sub, call language services at scale, and write to BigQuery.
• BigQuery directly: BigQuery can call Google’s AI services from inside SQL queries through remote model features, allowing analysts to enrich a table of text without leaving the warehouse. Check current documentation for the available functions.
• Cloud Run functions or Cloud Run: for simple, event-driven analysis when a file arrives or a form is submitted.
• Workflows and scheduled jobs: for nightly reprocessing and reports.

How to analyze millions of texts without slowing down or breaking quotas.

The service scales, your pipeline must too

The Natural Language API is a managed service, so Google handles the machinery. What you control is how fast you send requests, how you handle limits and how you retry. Your pipeline should be designed so that the slowest or most limited part sets a steady pace, with buffers before it.

Practical techniques

• Use a queue as a buffer: Pub/Sub lets you accept text at any speed and process at a safe, steady speed.
• Process in parallel, within quotas: run several workers at once, but cap the total request rate below your quota.
• Retry with backoff: if the service says “too many requests” or has a brief problem, wait a short time and try again, increasing the wait each time.
• Combine features per call: one call with several features beats several calls.
• Skip repeats: if the same text appears many times, such as a standard auto-reply, analyze it once and reuse the result.
• Filter first: do not analyze empty text, tiny fragments or machine-generated notices that carry no meaning.
• Keep the work close: run your workers in a region near your data and the service, to reduce delay.
• Request quota increases early: if you expect a large launch, ask in advance.

Latency

A single call to the classic API is usually quick, often well under a second for short text, though it depends on the text size and features chosen. Generative models take longer, because they produce text step by step. If a user is waiting on screen, measure the real delay and keep the slow work out of the page’s critical path.

Long documents

For very long documents, split the text into sensible chunks, such as chapters or paragraphs, analyze each one, and then combine the results. Be careful when combining: averaging sentiment can hide strong feelings, so keep the sentence-level results and the highest and lowest values as well.

AI reads quickly, but it does not read perfectly. Plan for that from the start.

Why mistakes happen

• Context: the same words mean different things in different situations. “Sick” can mean ill or excellent.
• Sarcasm and humor: tone is hard to detect in plain text.
• Domain language: specialist fields use words in special ways. In finance, “a short” is not a small thing.
• Mixed languages: messages that mix two languages, common in many regions, confuse models.
• Short text: a single word such as “fine” can be warm or cold.
• Spelling and style: typos, abbreviations and emoji may be handled imperfectly.
• Changing language: new slang appears faster than models are updated.

Fairness and bias

Language models learn from large collections of human writing, which may include unfair patterns. As a result, a model might treat text written in certain dialects, or text mentioning certain groups, differently from other text. This can lead to unfair results, such as wrongly flagging harmless posts from some communities. You should test your system with varied examples, look for patterns of unfair errors and avoid using model output alone for decisions that seriously affect people’s lives, such as hiring or credit.

Practical protections

• Measure on your own data. Take a few hundred real messages, have people label them, and compare with the model. This is your true accuracy.
• Use confidence and thresholds. Send uncertain items to people.
• Keep humans in the loop for high-stakes decisions. Automate the easy cases and review the rest.
• Provide appeals. If users are affected, let them challenge a result.
• Monitor drift. Periodically sample new data, since language and customer behavior change.
• Be honest about limits. Tell business users that scores are estimates, not facts.

Text often contains private details. Protect it before, during and after analysis.

Controlling access

Use Identity and Access Management (IAM) so that only approved programs and people can call the API and read results. Run each application with its own service account and give it only the permissions it needs. This is the principle of least privilege. Avoid long-lived keys stored in code, and avoid embedding simple API keys in apps that run on users’ devices.

Protecting data in transit and at rest

Requests to Google Cloud APIs travel over encrypted connections. Results you store in BigQuery or Cloud Storage are encrypted at rest by default, and you can use customer-managed keys if your policies require it. Private connectivity options keep traffic from your cloud network to Google’s services off the public internet.

Reducing what you send

The safest private data is the data you never send. Before analysis, remove or mask details you do not need, such as card numbers, government ID numbers, health details and passwords. Google’s Sensitive Data Protection service can find and mask many such patterns automatically. Remember that for sentiment, the name of the person is usually unnecessary.

Data handling terms

Read Google’s current terms and documentation about how customer content is processed, whether it is used to improve services, and what logging occurs. Many organizations also need to confirm where data is processed, to meet rules on data location. Confirm the processing locations and options for each feature you use, and involve your legal and security teams early.

Network boundaries and auditing

For sensitive projects, security perimeters such as VPC Service Controls can reduce the risk of data leaving a protected boundary, where supported. Cloud Audit Logs record administrative activity and, if enabled, data access, which is helpful for investigations and compliance.

Protecting the results

Analysis results can themselves be sensitive. A table of “angry customers by name” or “employees flagged for toxic messages” deserves the same care as the original text. Limit who can see it, and delete it when it is no longer needed.

Keep watching both the service health and the quality of the answers.

There are two kinds of monitoring. Operational monitoring asks whether the system is working: are requests succeeding and how fast are they? Quality monitoring asks whether the answers are still good: is accuracy holding up as the language of your customers changes?

Operational signals

Quality signals

• Sampled human review: every week, have a person check a random set of results and record the agreement rate.
• Score distribution: chart the share of positive, neutral and negative results over time. A sudden shift may mean a real event, or a change in data or tools.
• Language mix: watch for new languages or formats that the pipeline was not designed for.
• Moderation outcomes: track how many flagged items are upheld or overturned on review.
• Business results: check whether using the insights actually improved something, such as faster responses to unhappy customers.

Logging with care

Logs help you find problems, but logs that include raw customer text can leak private information. Log identifiers and results, not the full text, unless there is a strong reason and strict access controls.

Language analysis is billed by the amount of text. Know the units and avoid surprises.

The Natural Language API is priced by usage. Historically, usage has been counted in units of text, where a unit is a fixed number of characters (often one thousand), and each feature you request is counted separately for the text it analyzes. There has typically been a monthly free allowance, and the price per unit becomes lower at higher volumes. Because these details change, always use Google’s official pricing page and calculator for current numbers. The general shape is what matters for planning.

Ways to keep spending sensible

• Request only the features you need. If you only need sentiment, do not also request syntax.
• Filter out useless text. Do not analyze empty messages, system notices or exact duplicates.
• Trim the text. Remove long email signatures, legal footers and quoted history before sending.
• Cache results. Reuse analysis for identical text.
• Mix tools wisely. Use the cheap classic API broadly, and the pricier generative model selectively.
• Sample when you can. For trend charts, analyzing a representative sample may be enough.
• Set budgets and alerts. Use Google Cloud budgets to warn you before costs run away, and cap runaway loops with rate limits in your code.
• Label resources. Make it clear which project and team spend what.

No tool is perfect. A good architect weighs both sides before choosing.

The main trade-offs, in plain words

• Convenience versus customization: ready-made is quick, but custom needs may outgrow it.
• Predictability versus flexibility: classic APIs give steady output, while generative models give freedom with more variation.
• Cost versus depth: cheap broad analysis for everything, or costly deep analysis for a few items.
• Speed versus quality checks: fully automatic is fastest, but human review improves trust.
• Privacy versus insight: the more you remove from text, the safer it is, but too much removal can reduce meaning.

Related Google Cloud tools at a glance

A pattern is a proven way to solve a common problem. An anti-pattern is a tempting mistake that causes pain later.

Helpful patterns

Anti-patterns to avoid

A checklist you can follow from the first day.

Best practices

1. Start with a clear question. Decide what decision the analysis will support before building anything.
2. Try a small sample first. Run a few hundred real messages and review the results with people who know the business.
3. Choose the lightest tool that works. Classic API first, generative models where flexibility is needed, custom models when justified.
4. Clean and mask text before analysis. Remove noise and sensitive details.
5. Request only needed features. It saves money and time.
6. Use score and magnitude together. And use entity sentiment for product-level insight.
7. Set thresholds from your own data. Do not copy someone else’s cutoffs.
8. Keep humans in the loop. Review uncertain and high-impact items.
9. Buffer with Pub/Sub and handle retries. Respect quotas with backoff.
10. Store results with IDs and versions. Keep the original text and note which tool version made each result.
11. Use least privilege and managed identities. No secrets in code.
12. Monitor quality, not only uptime. Sample and re-check regularly.
13. Set budgets and alerts. Protect against runaway usage.
14. Check the latest documentation. Features, versions, languages, limits and prices change.

Common mistakes

Four illustrative stories show where language AI fits. The companies below are imaginary examples to teach the ideas.

When the Natural Language API is a strong choice

• You need standard analysis, such as sentiment, entities, topics or moderation, at large scale.
• You want quick results without training or hosting your own models.
• You value predictable, structured output and predictable costs.
• You are already building on Google Cloud data and analytics services.

When to think twice

• You need custom labels or custom fields that the built-in features do not provide.
• Your texts are mostly in languages or specialist domains where accuracy is not good enough in your tests.
• You need summaries, rewrites or answers, where generative models are better suited.
• Your rules forbid sending the text to an external managed service, or the data location does not meet your requirements.

Quick answers to questions that beginners ask most often.