Connecting to Google’s Natural Language API with Python on App Engine

Introduction

As part of our recent White October Hack Day, I did something very basic using Google’s Natural Language API to extract a list of nouns from a sentence.

The detail of what I used it for isn’t important here. What is important is that — perhaps understandably for a beta service — there was a definite lack of a “hello world” sample showing the basic of how to connect to and call the API.

This blog article is an attempt to rectify that!

The code

Enough talk, let’s see the code! I’ll then explain it line-by-line.

from lib.apiclient import discovery
lang_service = discovery.build(‘language’, ‘v1beta1’, developerKey=’your-key-here’)
the_data = {
“document”: {
“content”: “The cat sat on the mat”,
“type”:”PLAIN_TEXT”,
},
“encodingType”:”UTF8",
“features”: {
“extractSyntax”: True,
},
}
ret = lang_service.documents().annotateText(body=the_data).execute()

The detail

Account setup

To run this code in its entirety, you’ll need to have enabled billing on your App Engine account and you’ll need to enable the Google Cloud Natural Language API in your Google Cloud Platform console. To enable the API, go to API Manager from the “hamburger menu”, press the “Enable API” button and then use the search facility to find the Google Cloud Natural Language API. Alternatively, run this code without enabling it, and the code will throw an error giving you the exact URL you need to go to!

It’s enough to enable these in your Cloud Platform console — you don’t need to change anything in your dev instance of App Engine.

The code in detail

from lib.apiclient import discovery

This code requires the Google API Client Library for Python. This code sample assumes you have installed it with a command like:

pip install google-api-python-client -t app/lib

You then need to ensure your Google App Engine project includes code to add that folder to your vendor dependencies.

lang_service = discovery.build(‘language’, ‘v1beta1’, developerKey=’your-key-here’)

discovery.build provides access to the requested service. In this instance, ‘language’ is the service we’re connecting to, and ‘v1beta1’ is the version. You can check this list of all available Google APIs and versions if you want to connect to something else.

You can do authentication and authorisation with OAuth or with an API key. As this code sample doesn’t need to access private user data, an API key is enough. Instructions for creating an API key are here.

the_data = {
“document”: {
“content”: “The cat sat on the mat”,
“type”:”PLAIN_TEXT”,
},
“encodingType”:”UTF8",
“features”: {
“extractSyntax”: True,
},
}

You can see a description of the data structure we’re using on this page which lists all methods for the API and their parameters. For each method, the overall structure of the data to pass is specified. However, it doesn’t give examples of the values for each of the keys in this dictionary — some of them are just documented as “A String”! I got the details for those that were missing from the getting started guide for the API.

ret = lang_service.documents().annotateText(body=the_data).execute()

Here we actually make the call to the API. From here, we can see that the two top-level methods on the service are documents() and new_batch_http_request(). Drilling down into documents() makes it clear that this is the one we need. We can then see more details about each of its three methods: annotateText is the one I used, since I wanted to do syntax analysis.

Note that you pass the data as a Python dictionary; you don’t pass JSON. The API accepts JSON when being called via its URLs directly (like in this example), but in this code you are using the API Client Library which understands Python.

The return value from this call is a Python dictionary full of data about the sentence that’s been analysed. I won’t reproduce it here because it’s too long — just try the example for yourself!

Want to know more about our hack day? Our project was live-blogged here, and you can also check out #wohack on Twitter.

(This post was originally published on the White October blog here.)