Wiki-Data beta

You can request data in JSON, text or HTML format. Requesting in HTML format produces the same result as visiting the website in a browser. A JSONP wrapper is available to enable cross-domain data requests.

The endpoint for a search request is:

http://wiki-data.com/search

You can use the Accept HTTP header to choose the format of the response; alternatively, you can specify the format in the extension to the endpoint:

format	Accept header	endpoint
JSON	application/json	/search.json
text	text/plain	/search.txt
HTML	text/html	/search

JSONP requests

You can make cross-domain JSON search requests by specifying a jsonp_callback parameter in the query string. This wraps the returned data with a function call to whatever you choose as the value of the jsonp_callback parameter.

The API understands query string parameters delimited by either "&" or ";" characters, so both these requests are equivalent:

http://wiki-data.com/search.json?q=mycompany&jsonp_callback=myCallback
http://wiki-data.com/search.json?q=mycompany;jsonp_callback=myCallback

To make use of the JSONP callback, add a script tag to your page with the search query as the src - the callback will be executed as soon as the code is loaded:

var myCallback = function(response) {
// do something
};
var s = document.createElement('script');
s.src = "http://wiki-data.com/search.json?
	q=mycompany&jsonp_callback=myCallback";
document.head.appendChild(s);

If you use jQuery in your application, you can make use of its in-built JSONP handling:

$.getJSON(
	"http://wiki-data.com/search.json?q=mycompany&jsonp_callback=?",
	function(response) {
		// do something
	}
);

Fields to search data by - open fields

The simplest query you can make is by using the q parameter in the query string. This searches Legal Name, Previous Name(s) and Trades As Names(s) fields for a match

You can search the public data by any of the following fields. The query string parameter is the human-readable field name transformed to lower-case with " ", "(" and ")" replaced by "_":

field	query string parameter
AVID	avid
Legal Name	legal_name
Previous Name(s)	previous_name_s_
Trades As Names(s)	trades_as_name_s_
Trading Status	trading_status
Company Website	company_website
Country of Incorporation	registered_country
Operational PO Box	operational_po_box
Operational Street	operational_street_1
Operational Street 2	operational_street_2
Operational Street 3	operational_street_3
Operational City	operational_city
Operational Country	operational_country
Operational Postcode	operational_postcode

Country/state codes

For the state and country fields mentioned below, you need to provide the 2 or 3 letter ISO 3166 codes for the country/state you want.

There is a JavaScript helper library at http://github.com/jayfresh/ISO_3166 which contains the mappings you need.

field	code to use	reference
registered_country	ISO 3166-1 alpha 3	http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
operational_country	ISO 3166-1 alpha 3	http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
operational_state	ISO 3166-2	http://en.wikipedia.org/wiki/ISO_3166-2

Request query format

You can specify the fields to filter on in two different ways:

key/value pairs

This is standard form of creating a search string e.g. to search for all companies with the word "bank" in their name, operating in London, England, you can issue this query:

http://wiki-data.com/search?
	q=bank&operational_city=London&operational_country=GBR

field/value mapping

If you find that it is difficult to provide the key/value pair structure as described above, you might find it easier to use an indirect mapping of the fields to the values. For example, you might be presenting seperate inputs for someone to choose a field and provide a value (see the search filters on wiki-data.com).

To issue the same query as before, using the field/value mappping:

http://wiki-data.com/search?q=bank&adv_0_field=operational_city&
	adv_0_value=London&adv_1_field=operational_country&adv_1_value=GBR

For each extra field/value you want to search by, increase the index after adv_ by 1.

Requesting a search in JSON format returns data in the structure shown below. If you request data in HTML format, it returns the same webpage you would see if you performed the search on wiki-data.com. Searching in text format produces only a list of matching AVID's.

A JSON search returns data in this structure:

[
   {
      title: 12345678, // AVID
      fields: {
         legal_name,
         previous_name_s_,
         trades_as_name_s_,
         trading_status,
         company_website,
         registered_country,
         operational_po_box,
         operational_floor,
         operational_building,
         operational_street_1,
         operational_street_2,
         operational_street_3,
         operational_city,
         operational_state,
         operational_country,
         operational_postcode
      },
      // other meta-data fields about the record itself
   },
   ...
]

The other meta-fields referred to come from the internal structure of the TiddlyWeb instance running the system. We don't remove these as they may prove useful in some applications.

Individual company records are stored by AVID, which is an 8-digit identifier. A typical URL for a company record - in this case Avox Limited - is:

http://wiki-data.com/bags/avox/tiddlers/16835057

The URL reveals the internal structure of wiki-data as set up by TiddlyWeb - a collection of "tiddlers" (data entities) in a "bag" called "avox".

Records can be requested in different formats using the same mechanisms as for search - either by adding an extension to the URL or by setting an HTTP request Accept header to the appropriate value.

The formats available are the same as for search: JSON, text and HTML. Setting a JSONP callback for a record is supported in the same way as for search.

The Search API Version 2 was introduced in April 2011 and brings with it improvements in:

• Different types of search
• Ordering results by relevancy

To make use of any of the V2 abilities, any search needs to have v=2 as a parameter in the query.

Types of search

Searches to the V2 API can choose between three types of search, using the type parameter in the search query. The default option is "match all words". The following only apply to the query given as the q in a search request (on the wiki-data.com website, this is what is entered into the "Company Name/AVID" box).

Match all words (default)

This type of search matches all the words you have searched for, but not necessarily in the same order e.g. a search for "London bank" would match "The Royal Bank of Canada (London) Limited".

type=all
			
http://wiki-data.com/search?
	v=2&type=all&q=London%20bank

Partial match

This type of search matches either of the words you have searched for, as well as any words that start with the search terms e.g. a search for "London bank" would match "London Capital Management Ltd.", as well as "SOCIETE GENERALE Private Banking (Suisse) SA".

type=partial
			
http://wiki-data.com/search?
	v=2&type=partial&q=London%20Bank

Exact match

This type of search matches all the words you have search for in the order they are written e.g. a search for "insurance company" would match "Onebeacon Insurance Company" but not "Prudential Retirement Insurance and Annuity Company".

type=exact
			
http://wiki-data.com/search?
	v=2&type=exact&q=insurance%20company

Result relevancy

v2 of the search API has improved the way that search results are ordered, introducing a "relevancy factor". This is calculated based on the name fields - legal name, trading name(s) and previous name(s) - since these are the only fields that are not matched exactly.

The relevance of a search result will be higher if it:

• has more occurrences of the search query in its name fields
• has relatively more occurrences of the search query in its legal_name field
• is shorter than another result with the same number of occurrences of the search query

The algorithm used to calculate the relevancy factor is built into MySQL - see this page for more information.