krismuniz / google-kgsearch

A simple wrapper for Google's Knowledge Graph Search API.

google-kgsearch

google-kgsearch is a wrapper for Google's Knowledge Graph Search API. It is lightweight, simple, and easy to understand.

About Google's Knowledge Graph Search API:

The Knowledge Graph Search API lets you find entities in the Google Knowledge Graph. The API uses standard schema.org types and is compliant with the JSON-LD specification.

An excerpt from: https://developers.google.com/knowledge-graph/

Use cases

Some examples of how you can use the Knowledge Graph Search API include:

• Getting relevant information about a specific entity when doing Natural Language Processing
• Getting a ranked list of the most notable entities that match certain criteria.
• Predictively completing entities in a search box.
• Annotating/organizing content using the Knowledge Graph entities.

Quick Example: Search for a Person

Create a KGSearch instance with your API Key, store it in a variable (in this case: kGraph), and then call kGraph.search(params, callback)

import KGSearch from 'google-kgsearch'
const kGraph = KGSearch(process.env.KGSEARCH_API_KEY)

let params = {
  query: 'Taylor Swift',
  types: 'Person',
  limit: 1
}

kGraph.search(params, (err, items) => {
  if (err) console.error(err)
  console.log(items)
})

Outputs an object:

[
  {
    '@type': 'EntitySearchResult',
    result: {
      '@id': 'kg:/m/0dl567',
      name: 'Taylor Swift',
      '@type': [object],
      description: 'Singer-songwriter',
      image: [object],
      detailedDescription: [object],
      url: 'http://www.taylorswift.com/'
    },
    resultScore: 280.279816
  }
]

See the example for more information.

Installation

Installing google-kgsearch is as simple as installing any other npm module:

$ npm install google-kgsearch --save

Requirements

To use this API you need an API key. An API key identifies your project to check quotas and access. Go to the Credentials page to get an API key.

Check out Google Developers' guide for more information.

Usage

Initialization

After importing the google-kgsearch file, you need to initialize a new KGSearch instance with your API_TOKEN and store it in a variable (in this case its kGraph):

import KGSearch from 'google-kgsearch'
const kGraph = KGSearch(process.env.KGSEARCH_API_KEY)

Search Google's Knowledge Graph

Use the .search() method to search Google's Knowledge Graph.

/* ... */

kGraph.search({ query: 'Puerto Rico'}, (err, items) => {
  if (err) console.error(err)
  console.log(items)
})

The kGraph.search(params, callback) method takes params as a first argument. Under the hood the module converts these into query strings.

It also takes a callback function to handle the data received from the API.

reference

KGSearch

Argument	Type	Description
api_key (required)	string	Enables access to the Google's Knowledge Graph Search API

.search()

Method of KGSearch(api_key)

Argument	Type	Description
params (required)	object	API query parameters (query, types, limit, etc.)
callback (required)	function	A function that handles the response data from the API

callback takes two arguments:

1. err (for error handling; null if there are no errors)
2. data (the data returned by the API)

Contributing

Bug Reports & Feature Requests

Something does not work as expected or perhaps you think this module needs a feature? Please open an issue using GitHub's issue tracker. Please be as specific and straightforward as possible.

Developing

Pull Requests (PRs) are welcome. Make sure you follow the same basic stylistic conventions as the original code (i.e. "JavaScript standard code style")

License

The MIT License (MIT)

Copyright (c) 2016 Kristian Muñiz

google-kgsearch's Issues

Entity specific info

I am currently using your Knowlegde Graph search API in system which is a nice feature.
However I am very interested in the possibility of having it return information such as phone number and address (specific info for entity type as Organisation).
There for Iwant to kindly request that you add that to the API.  

Err is null

Thanks for the package. However we found that during error cases (invalid ids for example), err is null.

        kGraph.search(kg_params, (err, items) => {
            console.log(err);
            if (err) {
                console.log("error");
                Sentry.captureException(err);
                console.error(err);
            };

I am wondering how could this problem be fixed?