 |
|
|
|
 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
$1,700/$10,000 |  |
| Help us make Knowmore.org's goals for 2009 a reality! | About Our Fundraiser & Honor Roll | ||||||||||||||||||||
Knowmore.org Corporate Statistics API
From Knowmore.org
The Knowmore.org Corporate Statistics API, created originally for the KnowMore Firefox Extension, provides the corporate statistics profile of each and every corporation documented on Knowmore.org in a variety of accepted formats. From the very start, the API has been made available to the public with its features being documented on NetSquared and in the built-in documentation. Currently, the Knowmore.org Corporate Statistics API is considered to be of BETA status.
The Sunlight Foundation has described APIs as "the driving force behind modern mashups.[1]" And we couldn't agree with them more. Our API powers our Firefox Extension and we hope our API inspires developers to make mashups that use KnowMore's data to raise awareness about corporate abuses and empower ethical consumers.
Contents |
History of the API
Initially released in early May of 2008, the original version of the API wasn't hosted at Knowmore.org domain. Instead, it was hosted with a limited dataset on the currently inactive domain, knowmore.leftshoeuntied.org. Only after it was clear that the API functioned as intended was it uploaded to its current home of http://www.knowmore.org/wiki/api/api.php. This inaugural testing period lasted less than two weeks.
The API's initial release had it supporting a single data request and two formats-- profile, json and xml, respectively. Shortly after, the ratings and companyUrl request, or modules, were included. These modules, while working with the same data, provided the Knowmore.org data in a manner different than the initial profile module. The phtml format module, which produces the foundations of a 'widget', wasn't released until a few days after a NetSquared blog post hinted at its existence.
While considered to be fully functional and stable, the Knowmore.org Corporate Statistics API is a BETA release.
The API Dataset
The Knowmore.org Corporate Statistics API dataset contains the following information for a particular corporation:
- Company name
- Ratings in the categories of:
- Workers' rights
- Human rights
- Political influence
- Environmental impact
- Business ethics
- Issue summary
- URL for the Knowmore.org wiki
- Associated URLs (from the Brands section if present)
- Last update time.
Any further data provided by the API is derived by the original set.
Making an API Request
Making a request is something that is fairly simple to do with little or no experience. The process revolves around the core parameter of 'request' and the optional parameter of 'format'.
'request' Parameter
To make a valid API call, the request parameter is essential. A failure in specifiying the parameter will result in an error. Through the request parameter, the module used in the call is specified.
Syntax
request=request module
'format' Parameter
The optional format parameter is used to specifiy the output of the data generated by the API call. If excluded, the output will be defaulted to the JSON data format. Currently, three format modules are available for use--json, xml, and phtml.
Syntax
format=format module
How to Make a Request
Requests can be made from the Knowmore.org Corporate Statistics API at http://www.knowmore.org/wiki/api/api.php
To make proper call the request parameter must be specified. Calls are made in the format of api.php?request=module&format=module.
Additionally, certain modules have more parameters available to further specifiy the desired data. This would be in the format of api.php?request=module&format=module¶meter1=example1¶meter2=example2.
It should also be noted that call parameters--anything where parameter=value--do not have to be in any paritcular order. For example, api.php?parameter1=example1&request=module&format=module is valid in structure.
See below for a list of modules, their parameters, and examples.
Modules
Users can make requests for Knowmore.org company profile data through the use of something called a module. Each module has its own name--something that must be specified in the request--and its own parameters to filter and search the data.
The term 'module' is nothing more than a fancy name for a mechanism that returns a certain dataset.
request Modules
profile
The 'profile' module returns the entire dataset, plus its API ID and data flag.
Parameters
- company
- from
- flag
- url
- ratings set
- limit
Examples
api.php?request=profile&company=Target&format=xml
Will return the entire corporate statistics dataset for any company matching 'Target' in XML format
api.php?request=profile&flag=efrom=20080506
Will return any profile flagged as being 'extension-ready' that has been updated on or after May 6th, 2008 in the default JSON format
api.php?request=profile&human=1&format=xml
Will return all profiles with a human rights rating of 1 in XML format
For examples including output, please see the Full Examples section.
companyUrl
The 'companyUrl' module returns a list of associated URLs for a particular company. 'Associated URLs' is a term used to descirbe the URLs of a company profile's Brands & Subsidiaries section, if present. The company's main URL (nike.com for NIke Inc, for example) is also falls under the term.
Parameters
- company
- from
- flag
- ratings set
Examples
api.php?request=companyUrl
Will return a list of all company names and associated URLs from Knowmore.org
api.php?request=companyUrl&company=Wal-Mart
Will return a list of Wal-Mart's associated URLs
api.php?request=companyUrl&human=1
Will return a list of companies and their associated URLs that have a Human Rights rating of 1 (poor)
For examples including output, please see the Full Examples section.
ratings
The 'ratings' module returns the Knowmore.org ratings for a requested company or companies.
Parameters
- company
- from
- url
- kmurl
- issue
Examples
api.php?request=ratings
Will return a list of company names and Knowmore.org ratings for all profiles available at Knowmore.org
api.php?request=ratings&company=halliburton&issue=1
Will return the Knowmore.org ratings and issue summary for any company matching the term "Halliburton"
api.php?request=ratings&url=http://www.mmm.com
Will return the Knowmore.org ratings for the company associated with the http://www.mmm.com URL
format Modules
xml
The 'xml' format module returns output in a generic, simple XML format schema.
Structure
<profiles> <profile> <id>id</id> <company_name>company</company_name> <km_url>url</km_url> <data_flag>flag</data_flag> <issue_summary>summary</issue_summary> <update_time>time</update_time> <r_worker>0</r_worker> <r_human>0</r_human> <r_politics>0</r_politics> <r_enviro>0</r_enviro> <r_ethics>0</r_ethics>- <company_url> <url>url</url> </company_url> </profile> </profiles>
Expected Changes
While the current XML schema works fine for all reasonable purposes, it isn't considered to be in its final state. Expect changes to the structure of the XML within the coming weeks.
json
The 'json' format module outputs data in the JSON format in a structure similar to the XML format module.
Structure
{"profiles":[
{
"id":"id",
"company_name":"company",
"km_url":"url",
"data_flag":"flag",
"issue_summary":"summary",
"update_time":"time",
"r_worker":"0",
"r_human":"0",
"r_politics":"0",
"r_enviro":"0",
"r_ethics":"0",
"company_url" : [
"url",
"url"
]
}
]
}
phtml
The 'phtml', or 'pretty HTML', format module is a highly experimental and temporary module used to return a HTML code snippet to display a company's corporate statistics profile similar to the way it is displayed on Knowmore.org. The 'phtml' module is compatible with the 'profile' and 'ratings' request modules only. Issue summaries can be included through the 'issue' parameter.
Expected Changes
This module is expected to replaced by one of a similar function within the coming weeks.
Module Parameters
company
A given company's name, with partial matches available, in the form of a string.
- company=Wal - matches any company that starts with 'wal,' like Wal-Mart
- company=a - matches any company that begins with an 'a'
- company= - matches all companies, the same as excluding the parameter
from
A date in the form of YYYYMMDD, like 20080506; will match any company profile that has been updated on or after the selected date
- from=20080506 - matches all profiles updated on and after May 6th, 2005
- from= - matches all profiles, the same as excluding the parameter
flag
A means of filtering the dataset between 'extension-ready' profiles and all available profiles.
- flag=e - matches all profiles that have been marked as being 'extension-ready'
url
A URL, with partial matches available, in the format http://www.example.com
- url=http://www.walmart.com - matches any company associated with the walmart.com domain
ratings set
The ratings set is a short-hand way of referring to the five ratings available in a Knowmore.org corporate statics profile. Each rating can be a value between 1 and 3.
- Workers' rights
- Human rights
- Political influence
- Environmental impact
- Business ethics
kmurl
A Knowmore.org URL that points to a company profile in the format of http://www.knowmore.org/wiki/index.php?title=Example
issue
Issue is a special boolean parameter only available with the 'ratings' request module.
- issue=1 - returns issue summary to be paired with output
- issue=0 - does not return the issue summary of a particular company
