Fork me on GitHub
Skip to page content
 
DOL Home > OPEN > Developer Community > iOS Federal Data SDK

iOS 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 folder to your Xcode project.

Add Required Frameworks

Select your project and then select the project target in the middle pane. From the right pane select Build Phases. Expand the "Link Binary With Libraries" section. Add the required frameworks:

Frameworks
screenshot of frameworks to add

Using the SDK

Reference the DOL Data API in your source file

In the source files that will make DOL Data requests add the following imports:

#import "GOVDataRequest.h"
#import "GOVDataContext.h"

Prepare your class for delegate callbacks

The GOV Data SDK processes requests asynchronously to prevent locking up the UI while the data is requested and processed. To achieve this the SDK makes use of delegate methods. To successfully retrieve data it is required to implement the two GOVDataRequestDelegate methods and set your class as the delegate for the request. The methods will be invoked when the results have been processed or when an error occurs.

1. Implement the GOVDataRequestDelegate protocol to the class that will receive and process the API responses

Example:

@interface RootViewController : UITableViewController<GOVDataRequestDelegate>

2. Add the delegate methods to your class

//Results  delegate
-(void)govDataRequest:(GOVDataRequest *)request didCompleteWithResults:(NSArray *)resultsArray andResponseTime:(float)timeInMS {
     //for Standard DOL API datasets
	           //Add your code here
	           //resultsArray is an array of NSDictionaries
	           //One NSDictionary per table row 
    //for Standard DOL Data service - Summer job Plus,
	           //Add your code here
	           //resultsArray is an array of NSDictionaries
	           //Get the value of first key from NSDictionary in form of NSDictionaries.
		   //From NSDictionaries , look for "getJobsListing" which return the NSDictionary object.
		   //From getJobsListing object which is type of NSDictionaries , object using key "items" , result is an array , each element in array is job result.
			
}
 
-(void)govDataRequest:(GOVDataRequest *)request didCompleteWithDictionaryResults:(NSDictionary *)resultsDictionary andResponseTime:(float)timeInMS {
    
    // for web services that are not processed by the SDK as an array. For example, the FCC's Public Inspection Files API
    // consult the API's documentation regarding data structure or use NSLog to inspect the data
}
 
 
//Error delegate  
-(void)govDataRequest:(GOVDataRequest *)request didCompleteWithError:(NSString *)error {
	//Add your code here to show  / handle error
}
 
// Catch-all delegate
-(void)govDataRequest:(GOVDataRequest *)request didCompleteWithUnParsedResults:(NSString *)resultsString andResponseTime:(float)timeInMS {
 
    // Delegate to catch any data that could not be parsed
    
}

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 a NSDictionary as key/value pairs and passing it as the second parameter of the callAPIMethod method. Valid arguments are defined later in this document

  • Instantiate a GOVDataContext object
  • Instantiate a GOVDataRequest object and pass the context
  • Set your class as the delegate for the GOVDataRequest
  • Create a NSDictionary and store all the API arguments as key/value pairs.
  • Call the callAPIMethod method, passing the API name and the arguments (or null if there are no arguments)

Sample code to make requests for standard DOL API datasets:

//API  and URL constants
#define API_KEY @"YOUR API KEY" 
#define  API_HOST @"http://api.dol.gov"
#define API_URL @"/V1"
/////////////////////////////////////
 
//Instantiate  Gov Data context object
//This  object stores the API information required to make requests
GOVDataContext *context = [[GOVDataContext alloc] initWithAPIKey:API_KEY Host:API_HOST SharedSecret:API_SECRET APIURL:API_URL]
 
//Instantiate  new request object. Pass the context that contains all the API key info.  This object is used even when there is no API key.
GOVDataRequest *dataRequest = [[GOVDataRequest alloc]initWithContext:context];
 
//Set  this class as the one that responds to the delegate methods 
dataRequest.delegate = self; 
 
//API  you want to fetch data from 
NSString *method = @"FORMS/Agencies"; 
 
//Build NSDictionary arguments
//Example to retrieve top 10 records and just get one field. 
NSDictionary *arguments = [NSDictionary dictionaryWithObjectsAndKeys:@"10", @"top", @"AgencyName", @"select", nil];
 
//Set the timeout.  Set this higher for long-loading APIs
int timeOut = 20;
 
//Make API call
[dataRequest callAPIMethod:method withArguments:arguments andTimeOut:timeOut];

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://data.fcc.gov/api/block/find?latitude=40.0&longitude=-85

  • API_KEY = ""
  • API_SECRET = ""
  • API_Host = "http://data.fcc.gov"
  • API_URL = "/api/block"
  • 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 DOL Service Operation (e.g Summer Jobs Plus) :

//API  and URL constants
#define API_KEY @"YOUR API KEY" 
#define API_SECRET @"YOUR SHARED SECRET" 
#define  API_HOST @"http://api.dol.gov"
/////////////////////////////////////
 
//Instantiate  Gov Data context object
//This  object stores the API information required to make requests
GOVDataContext *context = [[GOVDataContext alloc] initWithAPIKey:API_KEY Host:API_HOST SharedSecret:API_SECRET APIURL:API_URL]
 
//Instantiate  new request object. Pass the context that contains all the API key info.  This object is used even when there is no API key.
GOVDataRequest *dataRequest = [[GOVDataRequest alloc]initWithContext:context];
 
//Set  this class as the one that responds to the delegate methods 
dataRequest.delegate = self; 
 
//API  you want to fetch data from 
NSString *method = @"SummerJobs/getJobsListing"; 
 
//Build NSDictionary arguments
//set value of format,query,region,locality and skipcount
//Please Note : 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.
//Each parameter that is assigned null should be left blank
 
//Please note:  the iOS SDK does not support the SummerJobs service at this time.
 
NSDictionary *arguments = [NSDictionary dictionaryWithObjectsAndKeys:@"'xml'", @"format", @"'farm'", @"query", @"", @"region", @"", @"locality", @"1", @"skipcount", nil];
 
//Set the timeout.  Set this higher for long-loading APIs
int timeOut = 20;
 
//Make API call
[dataRequest callAPIMethod:method withArguments:arguments andTimeOut:timeOut];

The callAPIMethod triggers the SDK to process the request, add authorization headers and invoke the delegate methods with the results or with an error message. Once the process has completed one of the three delegate methods from the GOVDataRequestDelegate protocol will be called. If successful, the didCompleteWithResults or didCompleteWithDictionaryResults method will be called and the resultsArray or resultsDictionary parameter, depending on the format of the data you received, will contain the data you requested. If the request failed for any reason, the didCompleteWithError will be called and the error parameter will contain a description of the error.

//Results  delegate
-(void)govDataRequest:(GOVDataRequest *)request didCompleteWithResults:(NSArray *)resultsArray {
     //for Standard DOL API datasets
	           //Add your code here
	           //resultsArray is an array of NSDictionaries
	           //One NSDictionary per table row 
    //for Standard DOL Data service - Summer job Plus,
	           //Add your code here
	           //resultsArray is an array of NSDictionaries
	           //Get the value of first key from NSDictionary in form of NSDictionaries.
		   //From NSDictionaries , look for "getJobsListing" which return the NSDictionary object.
		   //From getJobsListing object which is type of NSDictionaries , object using key "items" , result is an array , each element in array is job result.
			
}
 
-(void)govDataRequest:(GOVDataRequest *)request didCompleteWithDictionaryResults:(NSDictionary *)resultsDictionary {
    
    // for web services that are not processed by the SDK as an array. For example, the FCC's Public Inspection Files API
    // consult the API's documentation regarding data structure or use NSLog to inspect the data
}
 
 
//Error delegate  
-(void)govDataRequest:(GOVDataRequest *)request didCompleteWithError:(NSString *)error {
	//Add your code here to show  / handle error
}
 
// Catch-all delegate
-(void)govDataRequest:(GOVDataRequest *)request didCompleteWithUnParsedResults:(NSString *)resultsString {
 
    // Delegate to catch any data that could not be parsed
    
}

API Method Arguments

Standard DOL API datasets

top

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

Example:

NSDictionary *args = [NSDictionary dictionaryWithObject:@"2" forKey:@"top"];

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
NSDictionary  *arguments = [NSDictionary dictionaryWithObjectsAndKeys:@"10", @"top", @"20", @"skip", nil];

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 AgencyId and AgencyFormNumber columns
NSDictionary *args = [NSDictionary dictionaryWithObject:@"AgencyId,AgencyFormNumber" forKey:@"select"];

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 AgencyFormNumber column
NSDictionary *args = [NSDictionary dictionaryWithObject:@"AgencyFormNumber" forKey:@"orderby"];

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

For string comparisons enclose any multiple word string in single quotes. For example: 'Legal Identity Report'

More than one filter can be specified by joining them with the and/or keywords. Separate filters with parenthesis.
For example: (AgencyId eq 'MSHA') and (Title eq 'Legal Identity Report') retrieves the records where the value in the AgencyId column is equal to 'MSHA' and the value for the Title column is equal to 'Legal Identity Report'.

Example:

NSDictionary *args = [NSDictionary dictionaryWithObject: :@"(AgencyId eq  'MSHA') and (Title eq 'Legal Identity Report')" forKey:@"filter"];


Licenses

The GOVData and DOLData classes (whose file names start with GOVData or DOLData) are released to the Public Domain.

This SDK makes use of other libraries that are licensed differently. Please read them carefully.

SBJSON

/*
Copyright (C) 2009-2010 Stig Brautaset. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

* Neither the name of the author nor the names of its contributors may be used
to endorse or promote products derived from this software without specific
prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

MCCURLConnection

MCCURLConnection
Copyright (c), 2012 Thierry Passeron
The MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Reachability

Extensions Copyright (C) 2009 Donoho Design Group, LLC. All Rights Reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

* Neither the name of Andrew W. Donoho nor Donoho Design Group, L.L.C.
may be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY DONOHO DESIGN GROUP, L.L.C. "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/

/*

Apple's Original License on Reachability v2.0

Disclaimer: IMPORTANT: This Apple software is supplied to you by Apple Inc.
("Apple") in consideration of your agreement to the following terms, and your
use, installation, modification or redistribution of this Apple software
constitutes acceptance of these terms. If you do not agree with these terms,
please do not use, install, modify or redistribute this Apple software.

In consideration of your agreement to abide by the following terms, and subject
to these terms, Apple grants you a personal, non-exclusive license, under
Apple's copyrights in this original Apple software (the "Apple Software"), to
use, reproduce, modify and redistribute the Apple Software, with or without
modifications, in source and/or binary forms; provided that if you redistribute
the Apple Software in its entirety and without modifications, you must retain
this notice and the following text and disclaimers in all such redistributions
of the Apple Software.

Neither the name, trademarks, service marks or logos of Apple Inc. may be used
to endorse or promote products derived from the Apple Software without specific
prior written permission from Apple. Except as expressly stated in this notice,
no other rights or licenses, express or implied, are granted by Apple herein,
including but not limited to any patent rights that may be infringed by your
derivative works or by other works in which the Apple Software may be
incorporated.

The Apple Software is provided by Apple on an "AS IS" basis. APPLE MAKES NO
WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
COMBINATION WITH YOUR PRODUCTS.

IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR
DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF
CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF
APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Copyright (C) 2009 Apple Inc. All Rights Reserved.

*/

XMLReader

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.