PHP Federal Data SDK

Adding the SDK to Your Project

Add SDK files to your project

Extract the zipped SDK folder or grab the Git repository.

Copy the GOVDataSDK.php file into your project.

Requirements

This SDK makes use of PHP's cURL functions.

Using the SDK

Reference the GOV Data API in your source file

In the source files that will make GOV Data requests add the following include or require:

include "GOVDataSDK.php";

Making API Calls

The GOVDataRequest class is used to make API calls. It requires a context object to be passed to its constructor in order to get the API key and URL information needed for the requests. The GOVDataContext is the context class used to hold this information.

You can also pass arguments to the API call by adding them to an Array as key/value pairs and passing it as the second argument of the callAPI() method. Valid arguments include top, select, filter, orderby, and skip. They are defined later in this document.

In order to make requests:

Instantiate a GOVDataContext object
Instantiate a GOVDataRequest object and initialize it with the context
Create an Array and store all the API arguments as key/value pairs.
Call the callAPI() method, passing the API name and the arguments (leave off the arguments if there are no arguments)

Sample code to make requests for standard GOV API datasets:

<?php
include "GOVDataSDK.php";
 
//Instantiate  GOV Data context object
//This  object stores the API information required to make requests
if ($this->context->isValid() == "http://api.dol.gov") {
	$context = new GOVDataContext("http://api.dol.gov", "your-api-key", "your-shared-secret");
} 
//This  object stores the API information and does not require an API key or secret
elseif ($this->context->isValid() == "http://business.usa.gov") {
	$context = new GOVDataContext("http://business.usa.gov");
}
 
//Instantiate  new request object. Pass the context that contains all the API key info
$request = new GOVDataRequest $context;
 
//API  you want to fetch data from
$method = "FORMS/Agencies";
//Gov API method added e.g,: Business USA Article for domain: {business.usa.gov}
$method = "api/article/xml";
 
//Build Array arguments
//Example to retrieve top 10 records and just get one field. 
$arguments = Array('top' => '10', 'select' => 'AgencyName');
$arguments = Array('top' => '10', 'select' => 'Title');
 
//Make API call
$results = $request->callAPI($method, $arguments);
if (is_string($results)) {
	//handle error
} else {
	//handle success
}
?>

Sample code to make requests for GOV Service Operation (e.g Summer Jobs Plus) :

<?php
include "GOVDataSDK.php";
 
//Instantiate  GOV Data context object
//This  object stores the API information required to make requests
$context = new GOVDataContext("http://api.dol.gov");
 
//Instantiate  new request object. Pass the context that contains all the API key info
$request = new GOVDataRequest $context;
 
//API  you want to fetch data from
$method = "SummerJobs/getJobsListing";
 
//Build Array arguments
//Example to retrieve top 10 records and just get one field. 
$arguments =  Array('format' => '\'json\'', 
					'query' => '\'Farm\'',
					'region' => '',
					'locality' => '', 
					'skipCount' => '1');
 
 
//Make API call
$results = $request->callAPI($method, $arguments);
if (is_string($results)) {
	//handle error
} else {
	//handle success
}
?>

Using This SDK With APIs From Other Federal Agencies

The example above uses DOL's API. Some federal APIs' URLs are structured differently. For example, let's look at http://business.usa.gov/api/article/xml

API_KEY = ""
API_SECRET = ""
API_Host = "http://business.usa.gov"
API_URL = "/api/article/xml"
method = "find"

Let's look at the Census Bureau. For example, http://api.census.gov/data/2010/acs5?key={your key}&get=B02001_001E,NAME&for=state:06,36

API_KEY = "YOUR_API_KEY"
API_SECRET = ""
API_Host = "http://api.census.gov"
API_URL = "/data/2010"
method = "acs5"

Sample code to make requests for GOV Service Operation (e.g Business USA Article) :

<?php
include "GOVDataSDK.php";
 
//Instantiate  GOV Data context object
//This  object stores the API information required to make requests
$context = new GOVDataContext("http://business.usa.gov");
 
//Instantiate  new request object. Pass the context that contains all the API key info
$request = new GOVDataRequest $context;
 
//API  you want to fetch data from
$method = "api/article/xml";
 
//Build Array arguments
//Example to retrieve top 10 records and just get one field. 
$arguments =  Array('format' => '\'json\'', 
					'query' => '\'Title\'',
					'region' => '',
					'locality' => '', 
					'skipCount' => '1');
 
 
//Make API call
$results = $request->callAPI($method, $arguments);
if (is_string($results)) {
	//handle error
} else {
	//handle success
}
?>

The callAPI() triggers the SDK to process the request, add authorization headers and returns either an Array with the results or a String with an error message.

API Method Arguments

Standard GOV API datasets

top

The top argument is used to specify the number of records to be returned.

Example:

$args = Array('top' => '2');

skip

The skip argument specifies that you want the service to skip a specified number of results. This argument in combination with top, serve as the basis to implement pagination.

Example:

//Return records 21-30
$args = Array('top' => '10', 'skip' => '20');

select

The select argument allows you to specify the exact columns that you want the API to return. Separate them with commas if there is more than one.

In order to save bandwidth, it is always a good idea to add a select clause to most requests and retrieve the columns needed for a specific function. Some datasets can contain dozens of columns and the performance of your app can be impacted if you always return all of the columns. This is even more important in mobile applications because of device memory limitations, possible slow network speeds, and data usage caps imposed by carriers.

Example:

//Select the Article Node ID and other columns to display
$args = Array('select' => 'node,title,learn_more_url,publics_date,detailed_date,topic');

orderby

Use the orderby argument to sort the data by one or more columns. Separate them with commas if there is more than one.

//Order by the Title column
$args = Array('orderby' => 'title');

filter

The filter argument is used to add filters to the API query. For example, you can filter results where a specific column is equal to a string provided.

The API recognizes the following comparison keywords:

eq - Equal to

ne - Not Equal to

gt - Greater than

lt - Less than

ge - Greater than or equal to

le - Less than or equal to

GOV Service Operation for Summer Jobs Plus

To use the Service Operations API the Operation name and parameters need to be supplied using the data services format. Each String typed parameter must be surrounded in quotes in order to work correctly. These quotes are then Url encoded and passed to the Service Operation.

format

The format argument allows you to specify the format that the results string will be returned. If format argument is not passed with request then result will be returned in json format by default.
Following are the supported format of results string.

Format Codes:

json ( Default )

xml

atom

Example:

$arguments =  Array('format' => '\'json\'');

query

The query argument will be used to find matching job listings. This is required if region or locality are not provided.

Example:

$arguments =  Array('query' => '\'Farm\'');

region

The region argument will be used to filter jobs listings by the state name or abbreviation. This is required if query or locality are not provided.

Example:

$arguments =  Array('region' => '\'VA\'');

locality

The region argument will be used to filter jobs listings by The city name. This is required if query or region are not provided.

Example:

$arguments =  Array('locality' => '\'Alexandria\'');

skipCount

The skipCount argument will be used to specify the number of records to skip ahead from the first record. Valid range of 1-99 and it required.

Example:

$arguments =  Array('skipCount' => '1');