CARMA API v1.0 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.

Making an API Call

API Calls are simple GET request to one of the URLs listted below under API calls. Input parameters are specified using the familiar query string. A successful call will return a well-formed XML response encoded using UTF-8. If errors are encountered, an XML object with a value and description of the error are returned. Strings, such as "United States", will have to be URL encoded when passed in the URI.

Error Responses

An error reponse, returned if an input parameter is missing, incorrect, or if no matching data is found.

<?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 Calls

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

Function URL Description
getCompany http://carma.org/api/1.0/getCompany Returns information about a single company.
searchCompanies http://carma.org/api/1.0/searchCompanies Returns a list of companies matching search criteria.
getPlant http://carma.org/api/1.0/getPlant Returns information about a single plant.
searchPlants http://carma.org/api/1.0/searchPlants Returns a list of plants matching search criteria.
searchLocations http://carma.org/api/1.0/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.

Example API Calls:
http://carma.org/api/1.0/getCompany?name=DOMINION%20RESOURCES%20INC
http://carma.org/api/1.0/getCompany?stock=D
http://carma.org/api/1.0/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.

Example API Calls:
http://carma.org/api/1.0/searchCompanies?name=DOMINION%20RESOURCES%20INC
http://carma.org/api/1.0/searchCompanies?parent_company=784
http://carma.org/api/1.0/searchCompanies?location=202
http://carma.org/api/1.0/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.

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

searchPlants

Returns a list of plants matching search criteria. Returns an error response if no companies match. Parameters can be combined to narrow search results. Parameters can only be used once.

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)
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).

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

searchLocations

Returns a list of locations recognized by CARMA. Returns an error response if no locations match.

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%')

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