MyAvoxData.com, an Avox product

Using the MAD API

MAD exposes its data for reading in several formats through a HTTP API. You can try interacting with the API on this test page

Search request
Search response
Requesting individual records
Example application

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://myavoxdata.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

Authentication

To access records on MAD, you need to send authenticated requests. You can do this with either HTTP Basic Authentication or cookies. The authentication cookie is tiddlyweb_user.

Examples using the curl command-line tool:

Using HTTP Basic Authentication

curl -X GET -u : \
  http://www.myavoxdata.com/bags/avox/tiddlers/16835057.json

Using cookies

1) First use curl to post a username and password to the
login form's URL and store a cookie for it locally:
curl --cookie-jar cookies.txt -d \
  "username=&password=&submit=submit" \
  http://www.myavoxdata.com/challenge/tiddlywebplugins.wikidata.loginform

2) Pass the created cookie to subsequent API calls:
curl --cookie cookies.txt -X GET \
  http://www.myavoxdata.com/bags/avox/tiddlers/16835057.json

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://myavoxdata.com/search.json?q=mycompany&jsonp_callback=myCallback
http://myavoxdata.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://myavoxdata.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://myavoxdata.com/search.json?q=mycompany&jsonp_callback=?",
	function(response) {
		// do something
	}
);

Fields to search data by

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 also search by any of the following fields. The meaning of the fields is described in the Avox standard field spec. 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
SWIFT BIC	swift_bic
Company Website	company_website
Registration Number Jurisdiction	registration_number__jurisdiction_
Primary Listing Exchange	primary_listing_exchange
Ticker Code	ticker_code
Operational PO Box	operational_po_box
Operational Floor	operational_floor
Operational Building	operational_building
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
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 Country	registered_country
Registered Postcode	registered_postcode
NAICS Code	naics_code
NAICS Description	naics_description
US SIC Code	us_sic_code
US SIC Description	us_sic_description
Entity Type	entity_type
Immediate Parent AVID	immediate_parent_avid
Immediate Parent Name	immediate_parent_name
Ultimate Parent AVID	ultimate_parent_avid
Ultimate Parent Name	ultimate_parent_name

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
operational_state	ISO 3166-2	http://en.wikipedia.org/wiki/ISO_3166-2
operational_country	ISO 3166-1 alpha 3	http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
registered_state	ISO 3166-2	http://en.wikipedia.org/wiki/ISO_3166-2
registered_country	ISO 3166-1 alpha 3	http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3

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://myavoxdata.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 myavoxdata.com).

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

http://myavoxdata.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 myavoxdata.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_,
         ...
      },
      // other meta-data fields about the record itself
      revision: 0,
      recipe: null,
      bag: "avox",
      modified: "20100309143748",
      modifier: null,
      created: "",
      creator: null,
      type: null,
      tags: [],
      permissions: []
   },
   ...
]

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://myavoxdata.com/bags/avox/tiddlers/16835057

The URL reveals the internal structure of MAD as set up by TiddlyWeb - a collection of "tiddlers" (data entities) in a "bag" (permissioned collection of tiddlers) 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.

Example application

The wiki-data matcher is an example of an application built using the API for wiki-data.com, which is identical in structure to MAD's API.

This application adds the ability to enter search criteria that you are not sure of the accuracy for, and it looks for results using combinations of the criteria. You are presented with a list of results with a percentage against each, showing how much of a match to your search criteria they are.

MyAvoxData - an Avox product

Suggest a New Record

Search for a Record

About MAD