Search CARMA by country, state, province, county, metro area, city, power company,
power plant, or zip code.

Get the Data

This page provides documentation for users of the CARMA API. For more general information and searching and downloading the data, see the FAQ section.

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

Terms Of Use

The Center for Global Development encourages the use of CARMA’s data through the API. We are eager to learn how website developers are using the data, so please tell us about applications you are developing. Although users do not require an API key, CGD reserves the right to limit or terminate access at any time.

Making an API Call

The API uses simple GET requests to retrieve data. Each of the three methods (getCompanies, getPlants, and getLocations) has corresponding input parameters. A successful call will return a well-formed XML response encoded in UTF-8. An error response is returned if an input parameter is missing, incorrect, or if no matching data is found.

Error Response:

<?xml version=”1.0″ encoding=”UTF-8″>

<Error>

<Info>Longer description of the error, including tips on fixing it.</Info>

</Error>

Sample Input:

http://www.carma.org/api/getLocations?name=Morgantown

XML Returned:

<?xml version=”1.0″ encoding=”UTF-8″>

<Locations>

<Location>

<id>30714</id>

<name>Morgantown</name>

<region_type>city</region_type>

<province_country>United States</province_country>

<county_state>West Virginia</county_state>

</Location>

</Locations>

Quick Reference

To find a single company by ID:

  1. http://www.carma.org/api/getCompanies?id=700

To find a single company by stock symbol:

  1. http://www.carma.org/api/getCompanies?stock=SO

To find plants in Seattle:

  1. Search for a location by name (http://www.carma.org/api/getLocations?name=Seattle)
  2. Choose an ID from the resulting XML output (30599 in this case)
  3. Search plants with that location ID (http://www.carma.org/api/getPlants?location=30599)

To find plants owned by Dominion Virginia Power:

  1. Search for the company by name (http://www.carma.org/api/getCompanies?name=Dominion)
  2. Choose a company_id from the resulting XML output (4814 in this case)
  3. Search plants with that company_id (http://www.carma.org/api/getPlants?operating_company=4814)

getCompanies

Name Parameter Details
ID id (int) CARMA company ID.
Location location (int) Location ID, using a lookup from “getLocations”
Stock Symbol stock (str) Stock ticker symbol
Company Name name (str) Case-insensitive company name
Parent Company parent_company (int) Parent company ID, using a lookup from “getCompanies”

getPlants

Name Parameter Details
ID id (int) CARMA company ID.
Location location (id) Location ID, using a lookup from “getLocations”
Plant Name name (str) Case-insensitive plant name
Operating Companyoperating_company(int) Operating company ID, using a lookup from “getCompanies”

getLocations

Name Parameter Details
Location Name name (str) Case-insensitive location name