CARMA API v1.2 Documentation

The CARMA API provides REST-based access to data available on the CARMA site. Data is available in XML and JSON formats.

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.

Making an API Call

API Calls are simple GET request to one of the URLs listed below . Input parameters are specified using the familiar query string. A successful call will return a either a well-formed XML response or JSON string encoded using UTF-8. Strings, such as "United States", will have to be URL encoded when passed in the URI.

PHP Client

If you are using PHP5, you can use our handy CARMA PHP client to easily query data using the API without dealing with the underlying HTTP requests and parsing data.

Error Responses

An error reponse, returned if an input parameter is missing, incorrect, or if no matching data is found. An HTTP Status code of 404 is sent with any error reponse while JSON errors are returned as plain text and begin with the string "ERROR:". XML errors are returned in the following format:

<?xml version="1.0" encoding="UTF-8"?>
<error>
   <value>Input parameter XXX missing</name>
   <info>Longer description of error, including tips on fixing it.</info>.
</error>

API Methods Available

The REST API allows users to make 5 queries of the database, listed below.

Function URL Description
getCompany http://carma.org/api/1.2/getCompany Returns information about a single company.
searchCompanies http://carma.org/api/1.2/searchCompanies Returns a list of companies matching search criteria.
getPlant http://carma.org/api/1.2/getPlant Returns information about a single plant.
searchPlants http://carma.org/api/1.2/searchPlants Returns a list of plants matching search criteria.
searchLocations http://carma.org/api/1.2/searchLocations Returns a list of locations matching a name search.

getCompany

Returns company information based on ID (id), company name (name), or stock symbol (stock). One of the following parameters is required. If more than one is specified, the order of preference is ID, Stock Symbol, and finally Company Name. Returns an error response if no companies match.

Name Query String Parameter Description
Company Name name (String)The name of the company, as it appears on the HTML detail page.
Stock Symbol stock (String) The stock symbol the company trades under.
ID id (Integer) CARMA identifier for the plan. Returned as part of searchCompanies results.
Data Format format (String) Defines the data format to use, either 'xml' or 'json'. If not specified, defaults to xml.

Example API Calls:
http://carma.org/api/1.2/getCompany?name=DOMINION%20RESOURCES%20INC
http://carma.org/api/1.2/getCompany?stock=D
http://carma.org/api/1.2/getCompany?id=5049

searchCompanies

Returns a list of companies matching search criteria. Returns an error response if no companies match.

Name Query String Parameter Description
Company Name name (String)The name of the company. A case-insensitive match for any company name that contains the string supplied (ie. "LIKE '%dominion%')
Parent Company ID parent_company (Integer) The CARMA id of another company. Returns companies that are owned by the parent company.
Headquarter Country location (ID) Integer ID of a location in the CARMA database (see searchLocations). Returns an error if the location string is not recognized. This returns companies that are headquartered in that country.
CARMA Color color Returns companies that match a CARMA plant color (green, blue, yellow, orange, or red).
Data Format format (String) Defines the data format to use, either 'xml' or 'json'. If not specified, defaults to xml.

Example API Calls:
http://carma.org/api/1.2/searchCompanies?name=DOMINION%20RESOURCES%20INC
http://carma.org/api/1.2/searchCompanies?parent_company=3450
http://carma.org/api/1.2/searchCompanies?location=202
http://carma.org/api/1.2/searchCompanies?location=202&parent_company=784

getPlant

Returns company information based on ID (id), or plant name (name). One of the following parameters is required. If more than one is specified, the order of preference is ID, then Plant Name. Returns an error response if no plants match the criteria supplied.

Name Query String Parameter Description
Company Name name (String)The name of the plant, as it appears on the HTML detail page.
ID id (Integer) CARMA identifier for the plant. Returned as part of searchPlants results.
Data Format format (String) Defines the data format to use, either 'xml' or 'json'. If not specified, defaults to xml.

Example API Calls:
http://carma.org/api/1.2/getPlant?name=MOUNT%20STORM
http://carma.org/api/1.2/getPlant?id=101

searchPlants

Returns a list of plants matching search criteria. Parameters can be combined to narrow search results but can only be used once in a query. If no plants match the criteria, and error is returned.

Name Query String Parameter Description
Plant Name name (String)The name of the company. A case-insensitive match for any company name that begins with the string supplied (ie. "LIKE 'dominion%')
Operating Company ID operating_company (Integer) The CARMA id of a company. Returns plants operated by that company. (See searchCompanies)
Parent Company Id parent_company (Integer) The CARMA id of a company. Returns plants owned by that company.(See searchCompanies)
Location location
(id) Numeric id of a location in the CARMA db (see searchLocations). Returns an error if the location id is not recognized. This returns plants that are only in that location (could be Country/Province/City, et al).
US Zip Code zip A valid US Zip code. Returns plant located in that zip code.
CARMA Color color (String) Returns plants that match a CARMA plant color (green, blue, yellow, orange, or red).
Data Format format (String) Defines the data format to use, either 'xml' or 'json'. If not specified, defaults to xml.

Example API Calls:
http://carma.org/api/1.2/searchPlants?name=dominion
http://carma.org/api/1.2/searchPlants?operating_company=784
http://carma.org/api/1.2/searchPlants?location=2929
http://carma.org/api/1.2/searchPlants?location=299&operating_company=784

searchLocations

Returns a list of locations recognized by CARMA. Locations can be anything from a continent, province/state, down to an individual country or city. If no locations match the serch criteria, an error response is returned.

Name Query String Parameter Description
Location Name name (String)The name of the location A case-insensitive match for any company name that begins with the string supplied (ie. "LIKE 'united states%')
Region Type region_type (Integer) Returns regions of a specific type. 1 = continent, 2 = country, 3 = state/provice, 4 = metroarea, 5 = county, 6 = district, 7 = city
CARMA Color color (String) Returns regions that match a CARMA plant color (green, blue, yellow, orange, or red).
Data Format format (String) Defines the data format to use, either 'xml' or 'json'. If not specified, defaults to xml.

Example API Calls:
http://carma.org/api/1.2/searchLocations?name=Virginia

Advanced Examples

#1. Search for a US Congressperson by Name

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.2/searchLocations?name=James+Moran

#2. Get a Company from its Stock Symbol

http://carma.org/api/1.2/getCompany?stock=AEP

#3. Get All Plants Belonging to an Operating Company

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

http://carma.org/api/1.2/searchCompanies?name=Dupont&format=json

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 for the operating_company parameter in the searchPlants method.

http://carma.org/api/1.2/searchPlants?operating_company=5012&format=json

#4. Search for a Location

http://carma.org/api/1.2/searchLocations?name=Idaho

or to narrow by region_type (3=state):

http://carma.org/api/1.2/searchLocations?name=Idaho®ion_type=3

#5. Get All Plants Within a Location

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.2/searchPlants?location=1211

#6. Get All "Blue" Plants in Argentina

http://carma.org/api/1.2/searchLocations?name=Argentina&region_type=2

Argentina's location ID is 15. Use that ID for the next call, also setting color=blue

http://carma.org/api/1.2/searchPlants?location=15&color=blue