My Avox Data - an Avox product

Using the wiki-data API

wiki-data exposes its data in several formats through an API. To use the public data fields, you do not need a developer account. Non-public fields (as described in the field spec) are available with a developer account. At the moment, developer accounts are invite-only; if you would like to take advantage of the non-public fields, please get in touch at support@wiki-data.com

  1. Search request
    1. JSONP requests
    2. Open fields
    3. Private fields
    4. Country/state codes
    5. Request query format
  3. Search response

Search request

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
Registered Country registered_country
Operational PO Box operational_po_box
Operational Street 1 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

Fields to search data by - private fields

If you have a developer account, you also have access to the following fields:

field query string parameter
Avox Match Status avox_match_status
Avox Entity Class avox_entity_class
Avox Entity Type avox_entity_type
Record Source record_source
Name Notes name_notes
Legal Form legal_form
SWIFT BIC swift_bic
VAT Number vat_number
Tax Payer ID tax_payer_id
Registered By regulated_by
Regulator ID regulator_id
Regulatory Status regulatory_status
Registration Authority registration_authority
Registration Number Operational registration_number__operational_
Registration Number Jurisdiction registration_number__jurisdiction_
Date Of Registration date_of_registration
Date Of Dissolution date_of_dissolution
Issuer Flag issuer_flag
Primary Listing Exchange primary_listing_exchange
Ticker Code ticker_code
Fiscal Year End fiscal_year_end
MIFID Source mifid_source
Balance Sheet Date balance_sheet_date
Balance Sheet Currency balance_sheet_currency
Balance Sheet Total balance_sheet_total
Balance Sheet Turnover annual_net_turnover
Own Funds own_funds
Operational Address Notes operational_address_notes
Registered Agent Name registered_agent_name
Registered PO Box registered_po_box
Registered Floor registered_floor
Registered Building registered_building
Registered Street 1 registered_street_1
Registered Street 2 registered_street_2
Registered Street 3 registered_street_3
Registered City registered_city
Registered State registered_state
Registered Postcode registered_postcode
Registered Address Notes registered_address_notes
NAICS Code naics_code
NAICS Description naics_description
US SIC Code us_sic_code
US SIC Description us_sic_description
NACE Code nace_code
NACE Description nace_description
Entity Type entity_type
Immediate Parent AVID immediate_parent_avid
Immediate Parent Name immediate_parent_name
Immediate Parent Percentage Ownership immediate_parent_percentage_ownership
Immediate Parent Notes immediate_parent_notes
Ultimate Parent AVID ultimate_parent_avid
Ultimate Parent Name ultimate_parent_name
Ultimate Parent Notes ultimate_parent_notes
General Notes general_notes

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.

Search response

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.

Requesting individual records

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.