google_knowledge_graph 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e1d72961ddce5869648605bc27111604c38fc610a14bdf3e951813e5461a542c
+  data.tar.gz: b7a68aeb13bb398c736c0e70f34b777aed0d7fffe4a41955c44450f174273c7c
+SHA512:
+  metadata.gz: 2d8b790aa84d29eb1d4e934536d0d0ae178e6b14982d21f6b29f4091cd3409faf876ed552120e77da9ac7c6683e1970d5fa59bba5eb0411ae2774b0b33124036
+  data.tar.gz: 59519faabfd2572d89bc842aecc1ed1cb4f635f3411cd2dbc4ad9af0e9d157ecfa8445ba780b10223b1db60388c1a9442d358e99992073d11fa99494b22e3e2b

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,65 @@
+PATH
+  remote: .
+  specs:
+    google_knowledge_graph (0.1.0)
+      http (~> 4.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.3)
+    domain_name (0.5.20190701)
+      unf (>= 0.0.5, < 1.0.0)
+    ffi (1.12.2)
+    ffi-compiler (1.0.1)
+      ffi (>= 1.0.0)
+      rake
+    hashdiff (1.0.1)
+    http (4.4.1)
+      addressable (~> 2.3)
+      http-cookie (~> 1.0)
+      http-form_data (~> 2.2)
+      http-parser (~> 1.2.0)
+    http-cookie (1.0.3)
+      domain_name (~> 0.5)
+    http-form_data (2.3.0)
+    http-parser (1.2.1)
+      ffi-compiler (>= 1.0, < 2.0)
+    public_suffix (4.0.5)
+    rake (13.0.1)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.3)
+    safe_yaml (1.0.5)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.7)
+    webmock (3.8.3)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  google_knowledge_graph!
+  rspec (~> 3.0)
+  webmock (~> 3.0)
+
+BUNDLED WITH
+   2.1.4

data/README.md

@@ -0,0 +1,144 @@
+# google knowledge graph client
+
+A ruby client for Google's knowledge graph to:
+- getting a knowledge entity by id
+- searching entities, while set limits by types, languages, and score
+
+## Usage
+
+### installing
+
+```
+gem install google_knowledge_graph
+```
+or in your Gemfile
+```
+gem 'google_knowledge_graph'
+```
+then
+```
+bundle install
+```
+
+### config
+
+You'll need an API key to make a request, see the [doc](https://developers.google.com/knowledge-graph) for more information.
+
+```
+GoogleKnowledgeGraph.api_key = 'foo'
+```
+
+### getting knowledge entity by id
+
+> google knowledge graph responses entity result with @id like `kg:/m/0dl567`,
+  yet it expects id being `/m/0dl567` when querying the service
+
+```
+entity = GoogleKnowledgeGraph.get '/m/05pbsry'
+
+# the `data` field contains the original payload
+entity.data
+=> {
+  "url": "http://www.nbc.com/community-show/",
+  "detailedDescription": {
+    "url": "https://en.wikipedia.org/wiki/Community_(TV_series)",
+    "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
+    "articleBody": "Community is an American sitcom television series created by Dan Harmon that aired on NBC and Yahoo! Screen from September 17, 2009, to June 2, 2015. "
+  },
+  "@id": "kg:/m/05pbsry",
+  "name": "Community",
+  "@type": [
+    "Thing",
+    "TVSeries"
+  ],
+  "description": "American sitcom",
+  "image": {
+    "url": "https://www.wikiwand.com/en/Community_(TV_series)",
+    "contentUrl": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcRvfDLB01VDeWHLm-4R68LHym6-RzrQxe2PJF9aLNDw96kL7D-2"
+  }
+}
+```
+
+> For detail of the response, see [the reference](https://developers.google.com/knowledge-graph/reference/rest/v1)
+
+#### shorthand methods
+
+For your convenience, there're a few shorthand methods to `dig` into the data
+
+```
+entity.id
+=> 'kg:/m/05pbsry'
+
+entity.id_without_prefix
+=> '/m/05pbsry'
+
+entity.id_without_prefix
+=> '/m/05pbsry'
+
+entity.types
+=> ['Thing', 'TVSeries']
+
+entity.name
+=> 'Community'
+
+entity.url
+=> 'http://www.nbc.com/community-show/'
+
+entity.image
+=> {
+  'url': 'https://www.wikiwand.com/en/Community_(TV_series)',
+  'contentUrl': 'https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcRvfDLB01VDeWHLm-4R68LHym6-RzrQxe2PJF9aLNDw96kL7D-2'
+}
+
+entity.image_url # data.dig 'image', 'contentUrl'
+=> 'https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcRvfDLB01VDeWHLm-4R68LHym6-RzrQxe2PJF9aLNDw96kL7D-2'
+
+entity.description
+=> 'American sitcom'
+
+entity.detailed_description
+=> {
+  'license': 'https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License',
+  'articleBody': 'Community is an American sitcom television series created by Dan Harmon that aired on NBC and Yahoo! Screen from September 17, 2009, to June 2, 2015. ',
+  'url': 'https://en.wikipedia.org/wiki/Community_(TV_series)'
+}
+
+entity.description_text # data.dig 'detailedDescription', 'articleBody'
+=> 'Community is an American sitcom television series created by Dan Harmon that aired on NBC and Yahoo! Screen from September 17, 2009, to June 2, 2015. '
+
+entity.description_url # data.dig 'detailedDescription', 'url'
+=> 'https://en.wikipedia.org/wiki/Community_(TV_series)'
+```
+
+### searching entities
+
+```
+GoogleKnowledgeGraph.search 'community'
+=> [
+  {
+    entity: …,
+    score: 1000,
+  },
+  {
+    entity: …,
+    score: 800,
+  },
+  …
+]
+```
+
+#### options
+
+```
+GoogleKnowledgeGraph.search 'community', types: ['TVSeries']
+=> [
+  …
+]
+```
+
+> Currently, `types` is the only option being supported.
+> For detail of the options, see [the reference](https://developers.google.com/knowledge-graph/reference/rest/v1).
+
+## Development
+
+Use `rspec` or `bundle exec rspec` to run the test suite.

data/google_knowledge_graph.gemspec

@@ -0,0 +1,21 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+
+require 'google_knowledge_graph/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'google_knowledge_graph'
+  s.version     = GoogleKnowledgeGraph::VERSION
+  s.licenses    = ['MIT']
+  s.summary     = "Ruby client for Google's Knowledge Graph"
+  s.authors     = ['Nami WANG']
+  s.files       = `git ls-files -z`.split("\x0")
+  s.homepage    = 'https://github.com/ref-wiki/google_knowledge_graph'
+  s.metadata    = {
+    'source_code_uri' => 'https://github.com/ref-wiki/google_knowledge_graph'
+  }
+
+  s.add_development_dependency 'rspec', '~> 3.0'
+  s.add_development_dependency 'webmock', '~> 3.0'
+
+  s.add_runtime_dependency 'http', '~> 4.0'
+end

data/lib/google_knowledge_graph.rb

@@ -0,0 +1,56 @@
+require 'http'
+
+require 'google_knowledge_graph/entity'
+
+module GoogleKnowledgeGraph
+  API_URL = 'https://kgsearch.googleapis.com/v1/entities:search'
+
+  @api_key = nil
+
+  class << self
+    attr_accessor :api_key
+
+    def get id
+      ensure_api_key!
+      raise StandardError.new('InvalidIdStartingWithKG') if id.start_with? 'kg:'
+
+      response = request(
+        key: api_key,
+        limit: 1,
+        ids: [id]
+      )
+
+      return nil unless response.status.success?
+
+      Entity.new(response.body)
+    end
+
+    def search query, types: []
+      ensure_api_key!
+
+      response = request(
+        key: api_key,
+        query: query,
+        types: types,
+      )
+
+      return [] unless response.status.success?
+
+      JSON.parse(response.body)['itemListElement']
+        .map{ |item| {
+          entity: Entity.new(item['result']),
+          score: item['resultScore']
+        }}
+    end
+
+    private
+
+    def ensure_api_key!
+      raise StandardError.new('EmptyAPIKey') unless api_key
+    end
+
+    def request params
+      HTTP.get API_URL, params: params
+    end
+  end
+end

data/lib/google_knowledge_graph/entity.rb

@@ -0,0 +1,53 @@
+module GoogleKnowledgeGraph
+  class Entity
+    attr_reader :data
+
+    def initialize data
+      @data = data
+    end
+
+    def id
+      @data['@id']
+    end
+
+    def id_without_prefix
+      id.delete_prefix 'kg:'
+    end
+
+    def types
+      @data['@type']
+    end
+
+    def name
+      @data['name']
+    end
+
+    def url
+      @data['url']
+    end
+
+    def image
+      @data['image']
+    end
+
+    def image_url
+      @data.dig 'image', 'contentUrl'
+    end
+
+    def description
+      @data['description']
+    end
+
+    def detailed_description
+      @data['detailedDescription']
+    end
+
+    def description_text
+      detailed_description.dig 'articleBody'
+    end
+
+    def description_url
+      detailed_description.dig 'url'
+    end
+  end
+end

data/lib/google_knowledge_graph/version.rb

@@ -0,0 +1,3 @@
+module GoogleKnowledgeGraph
+  VERSION = '0.1.0'
+end

data/spec/fixtures/entity_data.json

@@ -0,0 +1,19 @@
+{
+  "url": "http://www.nbc.com/community-show/",
+  "detailedDescription": {
+    "url": "https://en.wikipedia.org/wiki/Community_(TV_series)",
+    "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
+    "articleBody": "Community is an American sitcom television series created by Dan Harmon that aired on NBC and Yahoo! Screen from September 17, 2009, to June 2, 2015. "
+  },
+  "@id": "kg:/m/05pbsry",
+  "name": "Community",
+  "@type": [
+    "Thing",
+    "TVSeries"
+  ],
+  "description": "American sitcom",
+  "image": {
+    "url": "https://www.wikiwand.com/en/Community_(TV_series)",
+    "contentUrl": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcRvfDLB01VDeWHLm-4R68LHym6-RzrQxe2PJF9aLNDw96kL7D-2"
+  }
+}

data/spec/fixtures/getting_entity.json

@@ -0,0 +1,36 @@
+{
+  "@context": {
+    "goog": "http://schema.googleapis.com/",
+    "kg": "http://g.co/kg",
+    "resultScore": "goog:resultScore",
+    "EntitySearchResult": "goog:EntitySearchResult",
+    "@vocab": "http://schema.org/",
+    "detailedDescription": "goog:detailedDescription"
+  },
+  "@type": "ItemList",
+  "itemListElement": [
+    {
+      "@type": "EntitySearchResult",
+      "result": {
+        "url": "http://www.nbc.com/community-show/",
+        "detailedDescription": {
+          "url": "https://en.wikipedia.org/wiki/Community_(TV_series)",
+          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
+          "articleBody": "Community is an American sitcom television series created by Dan Harmon that aired on NBC and Yahoo! Screen from September 17, 2009, to June 2, 2015. "
+        },
+        "@id": "kg:/m/05pbsry",
+        "name": "Community",
+        "@type": [
+          "Thing",
+          "TVSeries"
+        ],
+        "description": "American sitcom",
+        "image": {
+          "url": "https://www.wikiwand.com/en/Community_(TV_series)",
+          "contentUrl": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcRvfDLB01VDeWHLm-4R68LHym6-RzrQxe2PJF9aLNDw96kL7D-2"
+        }
+      },
+      "resultScore": 0
+    }
+  ]
+}

data/spec/fixtures/searching_entities.json

@@ -0,0 +1,296 @@
+{
+  "@context": {
+    "kg": "http://g.co/kg",
+    "@vocab": "http://schema.org/",
+    "goog": "http://schema.googleapis.com/",
+    "EntitySearchResult": "goog:EntitySearchResult",
+    "resultScore": "goog:resultScore",
+    "detailedDescription": "goog:detailedDescription"
+  },
+  "@type": "ItemList",
+  "itemListElement": [
+    {
+      "resultScore": 4182.677734375,
+      "result": {
+        "name": "Community",
+        "image": {
+          "url": "https://zh.wikipedia.org/wiki/File:East_Asian_Community.svg",
+          "contentUrl": "https://encrypted-tbn2.gstatic.com/images?q=tbn:ANd9GcRWLe5EY3TmNaXpA8MaaxounsLYmH_H0J8a8ypz9h_R8Vo4XnZ_"
+        },
+        "@type": [
+          "Thing"
+        ],
+        "@id": "kg:/m/01qls",
+        "detailedDescription": {
+          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
+          "url": "https://en.wikipedia.org/wiki/Community",
+          "articleBody": "A community is a social unit with commonality such as norms, religion, values, customs, or identity. Communities may share a sense of place situated in a given geographical area or in virtual space through communication platforms. "
+        }
+      },
+      "@type": "EntitySearchResult"
+    },
+    {
+      "result": {
+        "@type": [
+          "Thing"
+        ],
+        "name": "Community",
+        "detailedDescription": {
+          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
+          "url": "https://en.wikipedia.org/wiki/Community_(ecology)",
+          "articleBody": "In ecology, a community is a group or association of populations of two or more different species occupying the same geographical area at the same time, also known as a biocoenosis. The term community has a variety of uses. "
+        },
+        "@id": "kg:/g/120lq9cv"
+      },
+      "resultScore": 1027.097412109375,
+      "@type": "EntitySearchResult"
+    },
+    {
+      "@type": "EntitySearchResult",
+      "result": {
+        "@id": "kg:/m/05pbsry",
+        "@type": [
+          "Thing",
+          "TVSeries"
+        ],
+        "detailedDescription": {
+          "url": "https://en.wikipedia.org/wiki/Community_(TV_series)",
+          "articleBody": "Community is an American sitcom television series created by Dan Harmon that aired on NBC and Yahoo! Screen from September 17, 2009, to June 2, 2015. ",
+          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License"
+        },
+        "name": "Community",
+        "image": {
+          "url": "https://www.wikiwand.com/en/Community_(TV_series)",
+          "contentUrl": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcRvfDLB01VDeWHLm-4R68LHym6-RzrQxe2PJF9aLNDw96kL7D-2"
+        },
+        "url": "http://www.nbc.com/community-show/",
+        "description": "American sitcom"
+      },
+      "resultScore": 967.75714111328125
+    },
+    {
+      "resultScore": 125.786506652832,
+      "result": {
+        "name": "Online community",
+        "@id": "kg:/m/09k4rpx",
+        "detailedDescription": {
+          "articleBody": "An online community, also called an internet community or web community, is a virtual community whose members interact with each other primarily via the Internet. ",
+          "url": "https://en.wikipedia.org/wiki/Online_community",
+          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License"
+        },
+        "@type": [
+          "Thing"
+        ]
+      },
+      "@type": "EntitySearchResult"
+    },
+    {
+      "result": {
+        "@id": "kg:/g/11dxpv9v7r",
+        "@type": [
+          "Thing",
+          "Corporation",
+          "Organization"
+        ],
+        "name": "Shimmur, Inc.",
+        "description": "Company"
+      },
+      "resultScore": 95.504226684570312,
+      "@type": "EntitySearchResult"
+    },
+    {
+      "@type": "EntitySearchResult",
+      "resultScore": 94.383293151855469,
+      "result": {
+        "@type": [
+          "Thing"
+        ],
+        "@id": "kg:/m/0949wd",
+        "name": "Community",
+        "detailedDescription": {
+          "articleBody": "A community is an administrative division found in Belgium, Canada, Georgia, Greece, Iceland, Trinidad and Tobago, Ukraine, Wales, and the League of Nations Class A mandates.",
+          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
+          "url": "https://en.wikipedia.org/wiki/Community_(administrative_division)"
+        }
+      }
+    },
+    {
+      "@type": "EntitySearchResult",
+      "result": {
+        "name": "Community",
+        "@type": [
+          "Book",
+          "Thing"
+        ],
+        "description": "Book by Zygmunt Bauman",
+        "@id": "kg:/m/06rpcjb"
+      },
+      "resultScore": 89.038459777832031
+    },
+    {
+      "result": {
+        "detailedDescription": {
+          "url": "https://en.wikipedia.org/wiki/Community_(trade_union)",
+          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
+          "articleBody": "Community is a UK trade union which formed in 2004. The union represents workers in a diverse range of sectors, including iron and steel, domestic appliance manufacturing, clothing, textiles, footwear, road transport, betting and gaming and call centres, as well as workers in voluntary organisations, workshops for visually impaired and disabled people, community-care providers and housing associations. "
+        },
+        "name": "Community",
+        "image": {
+          "url": "https://en.wikipedia.org/wiki/Community_(trade_union)",
+          "contentUrl": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQ9TJBpc9YXhLPiBLg6FjCKkMtxPh0pCqRW9rU8vi93K7NtXbUO"
+        },
+        "@id": "kg:/m/09w295",
+        "@type": [
+          "Thing",
+          "Organization"
+        ],
+        "description": "Trade union"
+      },
+      "resultScore": 54.606101989746087,
+      "@type": "EntitySearchResult"
+    },
+    {
+      "resultScore": 52.932155609130859,
+      "result": {
+        "@type": [
+          "Thing",
+          "Corporation",
+          "Organization"
+        ],
+        "description": "Company",
+        "@id": "kg:/g/11fy28qjb3",
+        "name": "Origin Bank"
+      },
+      "@type": "EntitySearchResult"
+    },
+    {
+      "result": {
+        "@type": [
+          "Thing"
+        ],
+        "@id": "kg:/m/04vzrb",
+        "name": "Community",
+        "detailedDescription": {
+          "articleBody": "A community is a division of land in Wales that forms the lowest tier of local government in Wales. Welsh communities are analogous to civil parishes in England. In 2016 there were 870 communities in Wales.\nUntil 1974 Wales was divided into civil parishes. ",
+          "url": "https://en.wikipedia.org/wiki/Community_(Wales)",
+          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License"
+        }
+      },
+      "resultScore": 29.166910171508789,
+      "@type": "EntitySearchResult"
+    },
+    {
+      "resultScore": 7,
+      "result": {
+        "@id": "kg:/g/11jg4yxs03",
+        "name": "Community",
+        "@type": [
+          "Thing"
+        ]
+      },
+      "@type": "EntitySearchResult"
+    },
+    {
+      "resultScore": 7,
+      "result": {
+        "name": "Community",
+        "@id": "kg:/g/11b8c6hfq7",
+        "@type": [
+          "Thing"
+        ]
+      },
+      "@type": "EntitySearchResult"
+    },
+    {
+      "@type": "EntitySearchResult",
+      "resultScore": 7,
+      "result": {
+        "@id": "kg:/g/11j31d66yy",
+        "name": "Community",
+        "description": "Literary series",
+        "@type": [
+          "Thing",
+          "BookSeries"
+        ]
+      }
+    },
+    {
+      "result": {
+        "name": "Community",
+        "@id": "kg:/g/1q5j4dbr_",
+        "@type": [
+          "Thing"
+        ]
+      },
+      "resultScore": 7,
+      "@type": "EntitySearchResult"
+    },
+    {
+      "result": {
+        "name": "Community",
+        "@id": "kg:/g/11j60bn08p",
+        "@type": [
+          "Thing"
+        ]
+      },
+      "@type": "EntitySearchResult",
+      "resultScore": 7
+    },
+    {
+      "result": {
+        "@type": [
+          "Thing"
+        ],
+        "name": "Community",
+        "@id": "kg:/g/1q5jzbqnt"
+      },
+      "@type": "EntitySearchResult",
+      "resultScore": 7
+    },
+    {
+      "result": {
+        "name": "Community",
+        "@type": [
+          "Thing"
+        ],
+        "@id": "kg:/g/11j609507g"
+      },
+      "@type": "EntitySearchResult",
+      "resultScore": 7
+    },
+    {
+      "result": {
+        "name": "Community",
+        "@id": "kg:/g/11b6gpd__m",
+        "@type": [
+          "Thing"
+        ],
+        "description": "Fictional character"
+      },
+      "@type": "EntitySearchResult",
+      "resultScore": 7
+    },
+    {
+      "resultScore": 7,
+      "@type": "EntitySearchResult",
+      "result": {
+        "@id": "kg:/g/11h4ck18mm",
+        "@type": [
+          "Thing"
+        ],
+        "name": "Community"
+      }
+    },
+    {
+      "resultScore": 7,
+      "@type": "EntitySearchResult",
+      "result": {
+        "name": "Community",
+        "@id": "kg:/g/11hc_qh9dn",
+        "@type": [
+          "Thing"
+        ]
+      }
+    }
+  ]
+}

data/spec/fixtures/searching_entities_empty.json

@@ -0,0 +1,12 @@
+{
+  "@context": {
+    "detailedDescription": "goog:detailedDescription",
+    "EntitySearchResult": "goog:EntitySearchResult",
+    "goog": "http://schema.googleapis.com/",
+    "resultScore": "goog:resultScore",
+    "@vocab": "http://schema.org/",
+    "kg": "http://g.co/kg"
+  },
+  "@type": "ItemList",
+  "itemListElement": []
+}

data/spec/google_knowledge_graph/entity_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe GoogleKnowledgeGraph::Entity do
+  let(:entity_data){ JSON.parse File.read('spec/fixtures/entity_data.json') }
+  let(:entity){ GoogleKnowledgeGraph::Entity.new entity_data }
+
+  it 'init from data' do
+    expect(entity).to be_a GoogleKnowledgeGraph::Entity
+    expect(entity.data).to include entity_data
+  end
+
+  it 'provides shorthand methods' do
+    expect(entity.id).to eq 'kg:/m/05pbsry'
+    expect(entity.id_without_prefix).to eq '/m/05pbsry'
+    expect(entity.types).to eq ['Thing', 'TVSeries']
+    expect(entity.name).to eq 'Community'
+    expect(entity.url).to eq 'http://www.nbc.com/community-show/'
+    expect(entity.image).to include(
+      'url' => 'https://www.wikiwand.com/en/Community_(TV_series)',
+      'contentUrl' => 'https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcRvfDLB01VDeWHLm-4R68LHym6-RzrQxe2PJF9aLNDw96kL7D-2'
+    )
+    expect(entity.image_url).to eq 'https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcRvfDLB01VDeWHLm-4R68LHym6-RzrQxe2PJF9aLNDw96kL7D-2'
+    expect(entity.description).to eq 'American sitcom'
+    expect(entity.detailed_description).to include(
+      'license' => 'https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License',
+      'articleBody' => 'Community is an American sitcom television series created by Dan Harmon that aired on NBC and Yahoo! Screen from September 17, 2009, to June 2, 2015. ',
+      'url' => 'https://en.wikipedia.org/wiki/Community_(TV_series)'
+    )
+    expect(entity.description_text).to eq 'Community is an American sitcom television series created by Dan Harmon that aired on NBC and Yahoo! Screen from September 17, 2009, to June 2, 2015. '
+    expect(entity.description_url).to eq 'https://en.wikipedia.org/wiki/Community_(TV_series)'
+  end
+end

data/spec/google_knowledge_graph_spec.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+
+describe GoogleKnowledgeGraph do
+  before :each do
+    GoogleKnowledgeGraph.api_key = nil
+  end
+
+  context 'Version' do
+    it 'claims a version' do
+      expect(GoogleKnowledgeGraph::VERSION).not_to be_nil
+    end
+  end
+
+  context 'Configuration' do
+    it 'allows setting of the api_key' do
+      GoogleKnowledgeGraph.api_key = 'foo'
+      expect(GoogleKnowledgeGraph.api_key).to eq 'foo'
+    end
+  end
+
+  context 'Fetching knowledge entity' do
+    before :each do
+      GoogleKnowledgeGraph.api_key = 'foo'
+    end
+
+    describe '#self.get' do
+      it 'raises error for empty api_key' do
+        GoogleKnowledgeGraph.api_key = nil
+
+        expect {
+          GoogleKnowledgeGraph.get 'some_id'
+        }.to raise_error 'EmptyAPIKey'
+      end
+
+      it 'raise error for id starting with `kg:`' do
+        expect {
+          GoogleKnowledgeGraph.get 'kg:/m/05pbsry'
+        }.to raise_error 'InvalidIdStartingWithKG'
+      end
+
+      it 'returns an entity' do
+        stub_request(:get, 'https://kgsearch.googleapis.com/v1/entities:search?ids=/m/05pbsry&key=foo&limit=1')
+          .to_return(status: 200, body: File.read('spec/fixtures/getting_entity.json'))
+
+        expect(GoogleKnowledgeGraph.get '/m/05pbsry').to be_a GoogleKnowledgeGraph::Entity
+      end
+
+      it 'returns nil for bad request' do
+        stub_request(:get, /kgsearch.googleapis.com/)
+          .to_return(status: 403)
+
+        expect(GoogleKnowledgeGraph.get 'fakeid').to be_nil
+      end
+    end
+
+    describe '#self.search' do
+      it 'raises error for empty api_key' do
+        GoogleKnowledgeGraph.api_key = nil
+
+        expect {
+          GoogleKnowledgeGraph.search 'some query'
+        }.to raise_error 'EmptyAPIKey'
+      end
+
+      it 'returns an empty list for bad request' do
+        stub_request(:get, /kgsearch.googleapis.com/)
+          .to_return(status: 403)
+
+        expect(GoogleKnowledgeGraph.search 'some query').to eq []
+      end
+
+      it 'returns an empty list if nothing is found' do
+        stub_request(:get, 'https://kgsearch.googleapis.com/v1/entities:search?key=foo&query=somequerydoesnotexist')
+          .to_return(status: 200, body: File.read('spec/fixtures/searching_entities_empty.json'))
+
+        expect(GoogleKnowledgeGraph.search 'somequerydoesnotexist').to eq []
+      end
+
+      it 'returns a list of hash including entity and score' do
+        stub_request(:get, 'https://kgsearch.googleapis.com/v1/entities:search?key=foo&query=community')
+          .to_return(status: 200, body: File.read('spec/fixtures/searching_entities.json'))
+
+        expect(GoogleKnowledgeGraph.search 'community').to all include(
+          entity: a_kind_of(GoogleKnowledgeGraph::Entity),
+          score: be_a(Numeric)
+        )
+      end
+
+      it 'provides an option `types` to limit entity types' do
+        stub_request(:get, /kgsearch.googleapis.com\/v1\/entities:search/)
+          .to_return(status: 200, body: File.read('spec/fixtures/searching_entities.json'))
+
+        GoogleKnowledgeGraph.search 'community', types: ['TVSeries']
+
+        expect(
+          # not the standard types[]=a&types[]=b format
+          a_request(:get, 'https://kgsearch.googleapis.com/v1/entities:search?types=Thing&types=TVSeries')
+            .with(query: {
+              key: 'foo',
+              query: 'community',
+            })
+        ).to have_been_made.once
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'bundler/setup'
+Bundler.setup
+
+require 'google_knowledge_graph'
+
+require 'webmock/rspec'
+WebMock.disable_net_connect!(allow_localhost: true)
+
+# optional config
+# RSpec.configure do |config|
+# end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: google_knowledge_graph
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nami WANG
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-06-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- Gemfile
+- Gemfile.lock
+- README.md
+- google_knowledge_graph.gemspec
+- lib/google_knowledge_graph.rb
+- lib/google_knowledge_graph/entity.rb
+- lib/google_knowledge_graph/version.rb
+- spec/fixtures/entity_data.json
+- spec/fixtures/getting_entity.json
+- spec/fixtures/searching_entities.json
+- spec/fixtures/searching_entities_empty.json
+- spec/google_knowledge_graph/entity_spec.rb
+- spec/google_knowledge_graph_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/ref-wiki/google_knowledge_graph
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ref-wiki/google_knowledge_graph
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Ruby client for Google's Knowledge Graph
+test_files: []