├── .gitignore ├── kg-api.py └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | .api_key 3 | 4 | 5 | # Byte-compiled / optimized / DLL files 6 | __pycache__/ 7 | *.py[cod] 8 | 9 | # C extensions 10 | *.so 11 | 12 | # Distribution / packaging 13 | .Python 14 | env/ 15 | build/ 16 | develop-eggs/ 17 | dist/ 18 | downloads/ 19 | eggs/ 20 | lib/ 21 | lib64/ 22 | parts/ 23 | sdist/ 24 | var/ 25 | *.egg-info/ 26 | .installed.cfg 27 | *.egg 28 | 29 | # PyInstaller 30 | # Usually these files are written by a python script from a template 31 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 32 | *.manifest 33 | *.spec 34 | 35 | # Installer logs 36 | pip-log.txt 37 | pip-delete-this-directory.txt 38 | 39 | # Unit test / coverage reports 40 | htmlcov/ 41 | .tox/ 42 | .coverage 43 | .cache 44 | nosetests.xml 45 | coverage.xml 46 | 47 | # Translations 48 | *.mo 49 | *.pot 50 | 51 | # Django stuff: 52 | *.log 53 | 54 | # Sphinx documentation 55 | docs/_build/ 56 | 57 | # PyBuilder 58 | target/ 59 | 60 | # CloneDigger 61 | output.html 62 | 63 | config.py 64 | *.geojson 65 | html 66 | custom 67 | img/ 68 | *.ini 69 | -------------------------------------------------------------------------------- /kg-api.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | """ 3 | Query the Knowledge Graph API https://developers.google.com/knowledge-graph/ 4 | 5 | """ 6 | 7 | import argparse 8 | import datetime 9 | import requests 10 | import json 11 | import urllib 12 | 13 | 14 | def main(query): 15 | api_key = open('.api_key').read() 16 | service_url = 'https://kgsearch.googleapis.com/v1/entities:search' 17 | 18 | params = { 19 | 'query': query, 20 | 'limit': 5, 21 | 'indent': True, 22 | 'key': api_key, 23 | } 24 | 25 | url = service_url + '?' + urllib.urlencode(params) # TODO: use requests 26 | response = json.loads(urllib.urlopen(url).read()) 27 | 28 | # Parsing the response TODO: log all responses 29 | print('Displaying results...' + ' (limit: ' + str(params['limit']) + ')\n') 30 | for element in response['itemListElement']: 31 | try: 32 | types = str(", ".join([n for n in element['result']['@type']])) 33 | except KeyError: 34 | types = "N/A" 35 | 36 | try: 37 | desc = str(element['result']['description']) 38 | except KeyError: 39 | desc = "N/A" 40 | 41 | try: 42 | detail_desc = str(element['result']['detailedDescription']['articleBody'])[0:100] + '...' 43 | except KeyError: 44 | detail_desc = "N/A" 45 | 46 | try: 47 | mid = str(element['result']['@id']) 48 | except KeyError: 49 | mid = "N/A" 50 | 51 | try: 52 | url = str(element['result']['url']) 53 | except KeyError: 54 | url = "N/A" 55 | 56 | try: 57 | score = str(element['resultScore']) 58 | except KeyError: 59 | score = "N/A" 60 | 61 | print(element['result']['name'] \ 62 | + '\n' + ' - entity_types: ' + types \ 63 | + '\n' + ' - description: ' + desc \ 64 | + '\n' + ' - detailed_description: ' + detail_desc \ 65 | + '\n' + ' - identifier: ' + mid \ 66 | + '\n' + ' - url: ' + url \ 67 | + '\n' + ' - resultScore: ' + score \ 68 | + '\n') 69 | 70 | 71 | if __name__ == '__main__': 72 | parser = argparse.ArgumentParser() 73 | parser.add_argument('query', help='The search term to query') 74 | args = parser.parse_args() 75 | main(args.query) 76 | 77 | 78 | """ 79 | Sample result: https://kgsearch.googleapis.com/v1/entities:search?query=taylor+swift&key=[]&limit=1&indent=True 80 | 81 | { 82 | "@context": { 83 | "@vocab": "http://schema.org/", 84 | "goog": "http://schema.googleapis.com/", 85 | "EntitySearchResult": "goog:EntitySearchResult", 86 | "detailedDescription": "goog:detailedDescription", 87 | "resultScore": "goog:resultScore", 88 | "kg": "http://g.co/kg" 89 | }, 90 | "@type": "ItemList", 91 | "itemListElement": [ 92 | { 93 | "@type": "EntitySearchResult", 94 | "result": { 95 | "@id": "kg:/m/0dl567", 96 | "name": "Taylor Swift", 97 | "@type": [ 98 | "Thing", 99 | "Person" 100 | ], 101 | "description": "Singer-songwriter", 102 | "image": { 103 | "contentUrl": "http://t1.gstatic.com/images?q=tbn:ANd9GcQmVDAhjhWnN2OWys2ZMO3PGAhupp5tN2LwF_BJmiHgi19hf8Ku", 104 | "url": "https://en.wikipedia.org/wiki/Taylor_Swift", 105 | "license": "http://creativecommons.org/licenses/by-sa/2.0" 106 | }, 107 | "detailedDescription": { 108 | "articleBody": "Taylor Alison Swift is an American singer-songwriter. 109 | Raised in Wyomissing, Pennsylvania, she moved to Nashville, Tennessee, at the age of 14 110 | to pursue a career in country music. ", 111 | "url": "http://en.wikipedia.org/wiki/Taylor_Swift", 112 | "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License" 113 | }, 114 | "url": "http://www.taylorswift.com/" 115 | }, 116 | "resultScore": 884.364868 117 | } 118 | ] 119 | } 120 | """ 121 | 122 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # knowledge-graph-api 2 | 3 | ## Freebase 4 | 5 | Further background on Freebase and the deprecated Freebase APIs is available in my [freebase-mql](https://github.com/nchah/freebase-mql) repository. The KG API is a successor to the functionality once offered by the Freebase APIs. 6 | 7 | ## Google Knowledge Graph 8 | 9 | Google's Knowledge Graph is an internal knowledge base of linked data that draws from a wide range of sources for its data. The aforementioned Freebase database was one of the data sources. 10 | 11 | The Knowledge Graph allows the search engine to serve up the rich Knowledge Cards that take up the right side of many notable search results. 12 | 13 | The current KG API has more limited search capabilities compared to the previous Freebase API. It's currently not possible to craft queries (as was done in MQL) that return a sub-graph of Freebase topics. The best alternative will be to use the unique identifier (Freebase mid) and join it with other data, such as the growing volume on Wikidata. 14 | 15 | An example query: 16 | ``` 17 | $ python kg-api.py 'google' 18 | Google 19 | - entity_types: Thing, Organization, Corporation 20 | - description: Technology company 21 | - detailed_description: Google is an American multinational technology company specializing in Internet-related services and... 22 | - identifier: kg:/m/045c7b 23 | - url: N/A 24 | - resultScore: 287.675293 25 | 26 | Google X 27 | - entity_types: EducationalOrganization, Corporation, Organization, Thing 28 | - description: Corporation 29 | - detailed_description: X, previously Google X, is a semi-secret research and development facility created by Google and ope... 30 | - identifier: kg:/m/0hhrhd0 31 | - url: N/A 32 | - resultScore: 47.670715 33 | 34 | Googleplex 35 | - entity_types: Thing, Place 36 | - description: Building complex 37 | - detailed_description: The Googleplex is the corporate headquarters complex of Google, Inc., located at 1600 Amphitheatre P... 38 | - identifier: kg:/m/03bby1 39 | - url: http://www.google.com/about/jobs/locations/mountain-view/ 40 | - resultScore: 44.866741 41 | 42 | ``` 43 | 44 | 45 | ## Sources 46 | 47 | ### Announcements 48 | 49 | Many Freebase and Knowledge Graph related updates are posted on the once active [freebase-discuss](https://groups.google.com/forum/#!forum/freebase-discuss) Google Group and the [Google+](https://plus.google.com/u/0/109936836907132434202/posts) community. 50 | 51 | - Jul 16, 2010 (joining Google) https://groups.google.com/d/msg/freebase-discuss/NkCF1DayKzA/QQufQ9gDwBsJ 52 | - Dec 16, 2014 (timeline for Freebase sunsetting announced) https://plus.google.com/u/0/109936836907132434202/posts/bu3z2wVqcQc and https://groups.google.com/d/msg/freebase-discuss/s_BPoL92edc/Y585r7_2E1YJ 53 | - Mar 26, 2015 (details on Wikidata and new KG API projected) https://plus.google.com/u/0/109936836907132434202/posts/3aYFVNf92A1 54 | - Sep 28, 2015 (short update on KG API) https://plus.google.com/u/0/109936836907132434202/posts/3aYFVNf92A1 55 | - Dec 16, 2015 (KG Search API releasted) https://plus.google.com/u/0/109936836907132434202/posts/iY8NZGFF6DN 56 | - Jan 28, 2016 (KG Search Widget released) https://plus.google.com/u/0/109936836907132434202/posts/MCKpjUpx1H1 57 | - May 02, 2016 (Freebase.com shutdown) https://groups.google.com/forum/#!topic/freebase-discuss/WEnyO8f7xOQ 58 | 59 | ### Freebase 60 | 61 | - http://www.freebase.com/ (shutdown on May 02, 2016, now redirects to the data dumps) 62 | - http://wiki.freebase.com/wiki/Main_Page 63 | 64 | ### Knowledge Graph 65 | 66 | - https://en.wikipedia.org/wiki/Knowledge_Graph 67 | - https://googleblog.blogspot.ca/2012/05/introducing-knowledge-graph-things-not.html (May 16, 2012 official KG announcement) 68 | - https://www.google.com/intl/bn/insidesearch/features/search/knowledge.html (Google Inside Search explaining the Knowledge Graph) 69 | - http://searchengineland.com/laymans-visual-guide-googles-knowledge-graph-search-api-241935 (Search Engine Land provides a good tutorial) 70 | 71 | ### Google Developers Resources 72 | 73 | **Freebase APIs** 74 | - https://developers.google.com/freebase/ 75 | - https://developers.google.com/freebase/mql/ 76 | 77 | **Knowledge Graph Search APIs** 78 | - https://plus.google.com/109936836907132434202/posts/iY8NZGFF6DN (released on Dec 16, 2015) 79 | - https://developers.google.com/knowledge-graph/ 80 | - https://developers.google.com/knowledge-graph/reference/rest/v1/ (entities.search method's parameters) 81 | 82 | 83 | --------------------------------------------------------------------------------