Looking for API v1.0?

CARMA API v1.1 Documentation

The CARMA API provides REST-based access to data available on the CARMA site.

Terms of Use

Use of the API does not require an API key, although CGD/CARMA reserves the right to limit or terminate access to the API at any time. If you make use of the API, we ask that you be polite and limit how often you make a direct call to the server and cache the result of API calls locally.

Usage

http://carma.org/api/1.1/method_name?param1=value[¶m2=value&format=xml]

API calls either return a JSON or XML string or an error message (Ex: Error: no matching plants.) This data can then be easily parsed and used to create widgets and/or mashups. PHP5 comes with the built-in function, json_decode, which converts JSON into an array.

Method
Parameter
Description
getPlant
 
id
(int), get a plant by its CARMA ID
 
name
(string), get a plant by name
getCompany
 
id
(int), get a company by its CARMA ID
 
name
(string), get a company by name
 
symbol
(string), get a company by its stock ticker symbol
 
color
(string), CARMA company color (green, blue, yellow, orange, red)
searchPlants
 
name
(string), search for plants by name
 
location
(int), search for plants by the location ID
 
operating_company
(int), search for plants by their operating company ID (company_id)
 
parent_company
(int), search for plants by their parent company ID (parentcomp_id)
 
zip
(int), search for plants by zip code (USA only)
 
color
(string), CARMA plant color (green, blue, yellow, orange, red)
 
limit
(int), Maximum number of rows returned (no limit:0, default:2000)
 
raw
(int), No filtering (raw=1&limit=0 to download ALL plants)
searchCompanies
 
name
(string), search for companies by name
 
location
(int), search for companies by the location ID (continent or country)
 
parent_company
(int), search for companies by their parent company ID (parentcomp_id)
 
color
(string), CARMA company color (green, blue, yellow, orange, red)
 
limit
(int), Maximum number of rows returned (no limit:0, default:100)
 
raw
(int), No filtering (raw=1&limit=0 to download ALL companies)
searchLocations
 
name
(string), search for locations or congressmen by name
 
region_type
(int), 1=continent, 2=country, 3=state, 4=metro, 5=county, 6=district, 7=city
 
color
(string), CARMA region color (green, blue, yellow, orange, red)
 
limit
(int), Maximum number of rows returned (no limit:0, default:100)

Examples

Congressmen exist in the database as locations, because they represent a certain congressional district (location).
Let's start off by doing a search for James Moran using the searchLocations method.

http://carma.org/api/1.1/searchLocations?name=James Moran

This is a 2-step process. We first find the company ID from the searchCompanies method.

http://carma.org/api/1.1/searchCompanies?name=Dupont

When searching for the company Dupont, we will recieve a string of result data in JSON format.
Looking closely for the ID, and 5012 appears. Now use that ID in the searchPlants method.

http://carma.org/api/1.1/searchPlants?operating_company=5012

Looking at the JSON from example #4, Idaho has the location ID of 1211. Plug this into searchPlants and voila!

http://carma.org/api/1.1/searchPlants?location=1211