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

How to Use the PHP CARMA Client to Seamlessly Retrieve Data

At some point, working with any API involves making HTTP requests to retrieve data, followed by decoding that into a useful data structure for your own application. In the case of the CARMA API, there are five methods that can be called (getPlant, getCompany, searchPlants, searchCompanies,and searchLocations), and data can be returned as either JSON (Javascript Object Notation) or XML. Making HTTP requests and decoding the data returned can be a tedious, thankless operation, and, frankly, its not code that a lot of developers look forward to writing.

So, to make CARMA’s API even easier, we’re pleased to provide a PHP5 CARMA client that takes care of the low-level details and lets you focus on creating a cool widget or mash up with CARMA’s data.


The Carma PHP Client requires PHP5. It makes use of PHP’s native streams functionality to fetch data from the CARMA site. If you have the JSON extension, behind the scenes it will decode returned data, otherwise it falls back to using SimpleXML to parse XML data.

Download the Client

Download the PHP source code for the CARMA client here. You may need to right click and select “Save as..” from your browser’s context menu.

Basic Usage

I’ve tried to make the client as simple to use as possible, leaving the implementation details out of the way. After you download it, simply include it in your script and you’re ready to go. Here is a simple example for retrieving data for a plant whose ID we already know:

include('CarmaClient.php')$carma = new CarmaClient();$plant = $carma->getPlant(25097);// will display "LEWISTON MILL" and its dataecho $plant->name . " is operated by " . $plant->company->name . '';   

echo "<br />Current carbon output: " . number_format($plant->carbon->present, 2)';   

echo "<br />Future carbon output: " . number_format($plant->carbon->future, 2) ;

If you know the ID of a company in CARMA’s database, you can fetch the details for the company with one call. Continuing our example:

$company = $carma->getCompany(array("id" => $plant->company->id));

The searchPlants, searchCompanies, and searchLocations commands query the CARMA database in useful and revealing ways. These methods are available through the php client and will return an array of php objects. Let’s say we want to produce a list of companies in the state of Virginia in the USA. This is a two-step query; we need to figure out the locaiton ID for the state of Virginia, and then we can find the companies associated with that location.

First, we need to find the location ID of the state of Virginia:

$locations = $carma->searchLocations(array('name' => 'Virginia', 'type' => '3'));// carma api returns ANY location with the word Virginia in it so we have to filter the resultsforeach ($location as $loc) {   

    if ('Virginia' == $loc->name)   


        $va = $loc;   



Now we can find all the plants located in Virginia and list them:

$plants = $carma->searchPlants(array('location' => $va->id));echo "<p>There are " . $va->plant_count . " plants in Virginia.  They are: </p><ul>";foreach ($plants as $plant)   


    echo "<li>" . $plant->name .' -Future Carbon Output: ' . number_format($plant->carbon->future) ." tons </li>"   

}echo "</ul>"

CARMA’s data has infinite applications, as my colleague Matt Gibbs noted in an earlier post, and now it’s easier than ever to start creating great projects of your own. If you want to play with the CARMA API and have PHP available, please download the Carma Client and let us know how you are using it.

Information and Links

Join the fray by commenting, tracking what others have to say, or linking to it from your blog.

Other Posts

Write a Comment

Take a moment to comment and tell us what you think. Some basic HTML is allowed for formatting.

Reader Comments

Be the first to leave a comment!