Introduce Natural Language API

README.md

@@ -21,6 +21,7 @@ This client supports the following Google Cloud Platform services:
 * [Google Prediction API](#google-prediction-api)
 * [Google Translate API](#google-translate-api)
 * [Google Cloud Logging](#google-cloud-logging-beta) (Beta)
+* [Google Cloud Natural Language](#google-cloud-natural-language-beta) (Beta)
 * [Google Cloud Resource Manager](#google-cloud-resource-manager-beta) (Beta)
 * [Google Cloud Vision](#google-cloud-vision-beta) (Beta)
 
@@ -772,6 +773,90 @@ loggingClient.getEntries(function(err, entries) {
 ```
 
 
+## Google Cloud Natural Language (Beta)
+
+> **This is a Beta release of Google Cloud Natural Language.** This feature is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
+
+- [API Documentation][gcloud-language-docs]
+- [Official Documentation][cloud-language-docs]
+
+#### Using the all-in-one module
+
+```
+$ npm install --save google-cloud
+```
+
+```js
+var gcloud = require('google-cloud');
+var language = gcloud.language;
+```
+
+#### Using the Natural Language API module
+
+```
+$ npm install --save @google-cloud/language
+```
+
+```js
+var language = require('@google-cloud/language');
+```
+
+#### Preview
+
+```js
+// Authenticating on a per-API-basis. You don't need to do this if you auth on a
+// global basis (see Authorization section above).
+
+var languageClient = language({
+  projectId: 'grape-spaceship-123',
+  keyFilename: '/path/to/keyfile.json'
+});
+
+// Get the entities from a sentence.
+languageClient.detectEntities('Stephen of Michigan!', function(err, entities) {
+  // entities = {
+  //   people: ['Stephen'],
+  //   places: ['Michigan']
+  // }
+});
+
+// Create a document if you plan to run multiple detections.
+var document = languageClient.document('Contributions welcome!');
+
+// Analyze the sentiment of the document.
+document.detectSentiment(function(err, sentiment) {
+  // sentiment = 100 // Large numbers represent more positive sentiments.
+});
+
+// Parse the syntax of the document.
+document.annotate(function(err, annotations) {
+  // annotations = {
+  //   language: 'en',
+  //   sentiment: 100,
+  //   entities: {},
+  //   sentences: ['Contributions welcome!'],
+  //   tokens: [
+  //     {
+  //       text: 'Contributions',
+  //       partOfSpeech: 'Noun (common and proper)',
+  //       partOfSpeechTag: 'NOUN'
+  //     },
+  //     {
+  //       text: 'welcome',
+  //       partOfSpeech: 'Verb (all tenses and modes)',
+  //       partOfSpeechTag: 'VERB'
+  //     },
+  //     {
+  //       text: '!',
+  //       partOfSpeech: 'Punctuation',
+  //       partOfSpeechTag: 'PUNCT'
+  //     }
+  //   ]
+  // }
+});
+```
+
+
 ## Google Cloud Resource Manager (Beta)
 
 > **This is a Beta release of Google Cloud Resource Manager.** This feature is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
@@ -803,8 +888,8 @@ var resource = require('@google-cloud/resource');
 #### Preview
 
 ```js
-// Authorizing on a per-API-basis. You don't need to do this if you auth on a
-// global basis (see Authorization section above).
+// Authenticating on a per-API-basis. You don't need to do this if you auth on a
+// global basis (see Authentication section above).
 
 var resourceClient = resource({
   projectId: 'grape-spaceship-123',
@@ -858,8 +943,8 @@ var vision = require('@google-cloud/vision');
 #### Preview
 
 ```js
-// Authorizing on a per-API-basis. You don't need to do this if you auth on a
-// global basis (see Authorization section above).
+// Authenticating on a per-API-basis. You don't need to do this if you auth on a
+// global basis (see Authentication section above).
 
 var visionClient = vision({
   projectId: 'grape-spaceship-123',
@@ -975,6 +1060,7 @@ Apache 2.0 - See [COPYING](COPYING) for more information.
 [gcloud-compute-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/compute
 [gcloud-datastore-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/datastore
 [gcloud-dns-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/dns
+[gcloud-language-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/language
 [gcloud-logging-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/logging
 [gcloud-prediction-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/prediction
 [gcloud-pubsub-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/pubsub
@@ -1011,6 +1097,8 @@ Apache 2.0 - See [COPYING](COPYING) for more information.
 
 [cloud-dns-docs]: https://cloud.google.com/dns/docs
 
+[cloud-language-docs]: https://cloud.google.com/natural-language/docs
+
 [cloud-logging-docs]: https://cloud.google.com/logging/docs
 
 [cloud-prediction-docs]: https://cloud.google.com/prediction/docs

docs/toc.json

@@ -137,6 +137,14 @@
       "title": "Transaction",
       "type": "datastore/transaction"
     }]
+  }, {
+  }, {
+    "title": "Language",
+    "type": "language",
+    "nav": [{
+      "title": "Document",
+      "type": "language/document"
+    }]
   }, {
     "title": "Logging",
     "type": "logging",

packages/common/src/service-object.js

@@ -50,7 +50,7 @@ var util = require('./util.js');
  * @param {object} config - Configuration object.
  * @param {string} config.baseUrl - The base URL to make API requests to.
  * @param {string} config.createMethod - The method which creates this object.
- * @param {string} config.id - The identifier of the object. For example, the
+ * @param {string=} config.id - The identifier of the object. For example, the
  *     name of a Storage bucket or Pub/Sub topic.
  * @param {object=} config.methods - A map of each method name that should be
  *     inherited.
@@ -308,7 +308,7 @@ ServiceObject.prototype.request = function(reqOpts, callback) {
 
   var uriComponents = [
     this.baseUrl,
-    this.id,
+    this.id || '',
     reqOpts.uri
   ];
 

packages/common/test/service-object.js

@@ -606,6 +606,22 @@ describe('ServiceObject', function() {
       serviceObject.request(reqOpts, done);
     });
 
+    it('should not require a service object ID', function(done) {
+      var expectedUri = [
+        serviceObject.baseUrl,
+        reqOpts.uri
+      ].join('/');
+
+      serviceObject.parent.request = function(reqOpts) {
+        assert.strictEqual(reqOpts.uri, expectedUri);
+        done();
+      };
+
+      delete serviceObject.id;
+
+      serviceObject.request(reqOpts, assert.ifError);
+    });
+
     it('should support absolute uris', function(done) {
       var expectedUri = 'http://www.google.com';
 

packages/google-cloud/package.json

@@ -93,19 +93,20 @@
     "vision"
   ],
   "dependencies": {
+    "extend": "^3.0.0",
     "@google-cloud/bigquery": "0.1.0",
     "@google-cloud/bigtable": "0.1.0",
     "@google-cloud/compute": "0.1.0",
     "@google-cloud/datastore": "0.1.0",
     "@google-cloud/dns": "0.1.0",
-    "@google-cloud/prediction": "0.1.0",
+    "@google-cloud/language": "0.1.0",
     "@google-cloud/logging": "0.1.0",
+    "@google-cloud/prediction": "0.1.0",
     "@google-cloud/pubsub": "0.1.0",
     "@google-cloud/resource": "0.1.0",
     "@google-cloud/storage": "0.1.0",
     "@google-cloud/translate": "0.1.0",
-    "@google-cloud/vision": "0.1.0",
-    "extend": "^3.0.0"
+    "@google-cloud/vision": "0.1.0"
   },
   "devDependencies": {
     "proxyquire": "^1.7.10"

packages/google-cloud/src/index.js

@@ -127,6 +127,30 @@ var apis = {
    */
   dns: require('@google-cloud/dns'),
 
+  /**
+   * The [Google Cloud Natural Language](https://cloud.google.com/natural-language/docs)
+   * API provides natural language understanding technologies to developers,
+   * including sentiment analysis, entity recognition, and syntax analysis.
+   *
+   * <p class="notice">
+   *   **This is a Beta release of Google Cloud Natural Language.** This API is
+   *   not covered by any SLA or deprecation policy and may be subject to
+   *   backward-incompatible changes.
+   * </p>
+   *
+   * @type {module:language}
+   *
+   * @return {module:language}
+   *
+   * @example
+   * var gcloud = require('google-cloud');
+   * var language = gcloud.language({
+   *   projectId: 'grape-spaceship-123',
+   *   keyFilename: '/path/to/keyfile.json'
+   * });
+   */
+  language: require('@google-cloud/language'),
+
   /**
    * [Google Cloud Logging](https://cloud.google.com/logging/docs) collects and
    * stores logs from applications and services on the Google Cloud Platform:

packages/google-cloud/test/index.js

@@ -37,6 +37,7 @@ var FakeBigtable = createFakeApi();
 var FakeCompute = createFakeApi();
 var FakeDatastore = createFakeApi();
 var FakeDNS = createFakeApi();
+var FakeLanguage = createFakeApi();
 var FakeLogging = createFakeApi();
 var FakePrediction = createFakeApi();
 var FakePubSub = createFakeApi();
@@ -55,6 +56,7 @@ describe('gcloud', function() {
       '@google-cloud/compute': FakeCompute,
       '@google-cloud/datastore': FakeDatastore,
       '@google-cloud/dns': FakeDNS,
+      '@google-cloud/language': FakeLanguage,
       '@google-cloud/logging': FakeLogging,
       '@google-cloud/prediction': FakePrediction,
       '@google-cloud/pubsub': FakePubSub,
@@ -89,6 +91,10 @@ describe('gcloud', function() {
     assert.strictEqual(gcloud.dns, FakeDNS);
   });
 
+  it('should export static language', function() {
+    assert.strictEqual(gcloud.language, FakeLanguage);
+  });
+
   it('should export static logging', function() {
     assert.strictEqual(gcloud.logging, FakeLogging);
   });
@@ -193,6 +199,15 @@ describe('gcloud', function() {
       });
     });
 
+    describe('language', function() {
+      it('should create a new Language', function() {
+        var language = localGcloud.language(options);
+
+        assert(language instanceof FakeLanguage);
+        assert.strictEqual(language.calledWith_[0], options);
+      });
+    });
+
     describe('logging', function() {
       it('should create a new Logging', function() {
         var logging = localGcloud.logging(options);

packages/language/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@google-cloud/language",
+  "version": "0.1.0",
+  "author": "Google Inc.",
+  "description": "Google Cloud Natural Language Client Library for Node.js",
+  "contributors": [
+    {
+      "name": "Burcu Dogan",
+      "email": "jbd@google.com"
+    },
+    {
+      "name": "Johan Euphrosine",
+      "email": "proppy@google.com"
+    },
+    {
+      "name": "Patrick Costello",
+      "email": "pcostell@google.com"
+    },
+    {
+      "name": "Ryan Seys",
+      "email": "ryan@ryanseys.com"
+    },
+    {
+      "name": "Silvano Luciani",
+      "email": "silvano@google.com"
+    },
+    {
+      "name": "Stephen Sawchuk",
+      "email": "sawchuk@gmail.com"
+    }
+  ],
+  "main": "./src/index.js",
+  "files": [
+    "./src/*",
+    "AUTHORS",
+    "CONTRIBUTORS",
+    "COPYING"
+  ],
+  "repository": "googlecloudplatform/gcloud-node",
+  "keywords": [
+    "google apis client",
+    "google api client",
+    "google apis",
+    "google api",
+    "google",
+    "google cloud platform",
+    "google cloud",
+    "cloud",
+    "google cloud natural language",
+    "google cloud language",
+    "natural language",
+    "language"
+  ],
+  "dependencies": {
+    "@google-cloud/common": "^0.1.0",
+    "@google-cloud/storage": "^0.1.0",
+    "arrify": "^1.0.1",
+    "extend": "^3.0.0",
+    "google-proto-files": "^0.4.0",
+    "is": "^3.0.1",
+    "propprop": "^0.3.1",
+    "string-format-obj": "^1.0.0"
+  },
+  "devDependencies": {
+    "mocha": "^2.1.0",
+    "proxyquire": "^1.7.10"
+  },
+  "scripts": {
+    "publish": "../../scripts/publish.sh",
+    "test": "mocha test/*.js",
+    "system-test": "mocha system-test/*.js --no-timeouts --bail"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=0.12.0"
+  }
+}