https://github.com/kbarresi/wikidata-search

An npm package that allows easy entity searching of Wikidata.
https://github.com/kbarresi/wikidata-search

Last synced: about 1 month ago
JSON representation

An npm package that allows easy entity searching of Wikidata.

• Host: GitHub
• URL: https://github.com/kbarresi/wikidata-search
• Owner: kbarresi
• License: mit
• Created: 2015-10-06T04:21:28.000Z (over 9 years ago)
• Default Branch: master
• Last Pushed: 2017-03-31T09:19:27.000Z (about 8 years ago)
• Last Synced: 2024-08-01T12:33:44.609Z (9 months ago)
• Language: JavaScript
• Size: 13.7 KB
• Stars: 10
• Watchers: 2
• Forks: 6
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-starred - kbarresi/wikidata-search - An npm package that allows easy entity searching of Wikidata. (others)

README

        
wikidata-search

===============

Perform easy entity searches using Wikidata as a source.

What's an entity search? Basically, just give an entity name (person, place, thing, etc), and 

we'll run a query against the Wikidata API. We'll match it to the Wikidata entity that most 

closely matches what you searched, and return a bunch of structured data for that entity. For a

better idea of what this means, check out some of the examples below.

## Installation

  npm install wikidata-search

  

 

## Overview

wikidata-search provides two major functionalities: the ability to search for entities based on 

given (possibly incomplete) text, and the ability to get more detailed information about entities 

from their IDs. All of this is done is a clean way that (mostly) abstracts you from the headache

that is Wikidata. 

## Usage 

    //First, create a new Wikidata Search object.

    var WikidataSearch = require('wikidata-search').WikidataSearch;

    var wikidataSearch = new WikidataSearch();

    

    //To search:

    wikidataSearch.set('search', ); //set the search term

    wikidataSearch.search(function(result, error) {

   

        //check the 'error' parameter for any errors, and your results are in 'result'.

    });

    

    

    //To get detailed info on one or more entities:

    wikidataSearch.getEntities(['id', 'id', ...], true, function(result, error) {

        //check the 'error' parameter for any errors, and your results are in 'result'.

    });

    

    

## Important Functions

### WikidataSearch.set(key, value) 

Sets an option *key* to *value*.

    

### WikidataSearch.search(callback) 

Performs a search using the 'search' option (which should be set using 

WikidataSearch.set(key, value). The data returned has the following format:

    results : {   

        id : {String}, the ID of the result entity,

        url : {String}, the Wikidata URL for the entity,

        label : {String}, the string label for the entity (its name),

        description : {String}, the optional description of the entity, if available

    }

    

The `description` field is only available for entities (i.e. not properties).

### WikidataSearch.getEntities(entityIdList, resolveProperties, callback) 

    

Get detailed information for a list of entities who's IDs (strings) are listed in *entityIdList*.

The *resolveProperties* parameter determines whether the results have their property and value IDs

replaced with the corresponding labels (names) of the entities and properties. The result field will

look something like this:

    [ 

        { 

            label: 'New York Mets',

            description: 'baseball team and Major League Baseball franchise in Queens, New York, United States',

            claims: [ 

                { value: 'New York Mets', type: 'string', property: 'Commons category' },

                { value: 'Citi Field', type: 'string', property: 'home venue' },

                { value: 'Terry Collins', type: 'string', property: 'head coach' },

                { value: 'Major League Baseball', type: 'string', property: 'league' },

                { value: 'baseball team', type: 'string', property: 'instance of' },

                { value: 'Category:New York Mets', type: 'string', property: 'topic\'s main category' },

                { value: '/m/05g76', type: 'string', property: 'Freebase identifier' },

                { value: '134873843', type: 'string', property: 'VIAF identifier' },

                { value: 'baseball', type: 'string', property: 'sport' },

            ] 

        },

    ]

    

About the fields: *label* is a text label, and generally gives the name of the entity. *description*

is a text description of the entity. *claims* is a list of facts about the entity, given as 

property/value/type triplets.

A bit about the *resolveProperties* parameter: say a lookup result has a claim looking like this: 

    { 'property' : 'P1234', 'value' : 'Q1234', 'type' : 'wikidata-item' }

    

If property resolution is disabled (set to false), then that's exactly what you'll get back. If it's 

enabled, then we'll do a lookup for `P1234` and `Q1234`, and replace those IDs with their labels. So

it might look something like this if property resolution is enabled. Notice that the `type` field is

updated:

    { 'property' : 'is parent of', 'value' : 'Jim Bob', 'type' : 'string' }

    

Unfortunately, property resolution means it'll probably have to do two requests behind the scenes: one

to get the entity result, and another to populate the the properties with their labels. There's 

good news though! We cache these lookups, so once a property ID is resolved to a label, it's saved 

in memory. To clear the cache, use WikidataSearch.clearPropertyCache();

    

    

## Examples

See example.js for an example of how to use this.