United States Department of Labor

	All DOL  OSEC    Advanced Search
A to Z |  Site Map |  FAQs |  Forms |  About DOL |  Contact Us |  Español

iOS DOL Data SDK

Adding the SDK to Your Project

• Add SDK files to your project
• Add Required Frameworks

Using the SDK

• Reference the DOL Data API in your source file
• Prepare your class for delegate callbacks
• Making API Calls
• API Method Arguments
• Standard DOL API datasets
• top
• skip
• select
• orderby
• filter
• DOL Service Operation for Summer Jobs Plus
• format
• query
• region
• locality
• skipCount

Licenses

• SBJSON
• ASIHTTP
• Reachability

Adding the SDK to Your Project

Add SDK files to your project

Extract the zipped SDK folder.
Copy the DOLDataSDK 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:

• libz.1.2.3.dylib
• MobileCoreServices.framework
• CFNetwork.framework
• SystemConfiguration.framework

Frameworks

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 "DOLDataRequest.h"
#import "DOLDataContext.h"

Prepare your class for delegate callbacks

The DOL 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 DOLDataRequestDelegate 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 DOLDataRequestDelegate protocol to the class that will receive and process the API responses

Example:

@interface RootViewController : UITableViewController<DOLDataRequestDelegate>

2. Add the delegate methods to your class

//Results  delegate
-(void)dolDataRequest:(DOLDataRequest *)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.
			
}

//Error delegate  
-(void)dolDataRequest:(DOLDataRequest *)request didCompleteWithError:(NSString *)error {
	//Add your code here to show  / handle error
}

Making API Calls

The DOLDataRequest 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 DOLDataContext 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 DOLDataContext object
• Instantiate a DOLDataRequest object and pass the context
• Set your class as the delegate for the DOLDataRequest
• 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_SECRET @"YOUR SHARED SECRET" 
#define  API_HOST @"http://api.dol.gov"
/////////////////////////////////////

//Instantiate  DOL Data context object
//This  object stores the API information required to make requests
DOLDataContext *context = [[DOLDataContext alloc] initWithAPIKey:API_KEY Host:API_HOST SharedSecret:API_SECRET];

//Instantiate  new request object. Pass the context that contains all the API key info
DOLDataRequest *dataRequest = [[DOLDataRequest 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];

//Make API call
[dataRequest callAPIMethod:method withArguments:arguments];

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  DOL Data context object
//This  object stores the API information required to make requests
DOLDataContext *context = [[DOLDataContext alloc] initWithAPIKey:API_KEY Host:API_HOST SharedSecret:API_SECRET];

//Instantiate  new request object. Pass the context that contains all the API key info
DOLDataRequest *dataRequest = [[DOLDataRequest 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

NSDictionary *arguments = [NSDictionary dictionaryWithObjectsAndKeys:@"'json'", @"format", @"'farm'", @"query", @"", @"region", @"", @"locality", @"1", @"skipcount", nil];

//Make API call
[dataRequest callAPIMethod:method withArguments:arguments];

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 two delegate methods from the DOLDataRequestDelegate   protocol will be called. If successful, the didCompleteWithResults method will be called and the resultsArray parameter 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)dolDataRequest:(DOLDataRequest *)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.
}

//Error delegate  
-(void)dolDataRequest:(DOLDataRequest *)request didCompleteWithError:(NSString *)error {
	//Add your code here to show  / handle error
}

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"];

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
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"];

DOL 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. Each integer typed parameter must be entered without quotes in order to work correctly.Each parameter that is assigned null should be left blank.

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:

//Create a dictionary of arguments
 NSDictionary *arguments = [NSDictionary dictionaryWithObjectsAndKeys:@"'json'@", @"format@", nil];

query

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

Example:

//Create a dictionary of arguments
NSDictionary *arguments = [NSDictionary dictionaryWithObjectsAndKeys:@"'json'@", @"format@", @"'farm'", @"query", nil];

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:

//Create a dictionary of arguments
NSDictionary *arguments = [NSDictionary dictionaryWithObjectsAndKeys:@"'json'@", @"format@", @"'farm'", @"query", @"", @"region", nil];

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:

//Create a dictionary of arguments
NSDictionary *arguments = [NSDictionary dictionaryWithObjectsAndKeys:@"'json'@", @"format@", @"'farm'", @"query", @"", @"region",@"", @"locality", nil];

skipCount

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

Example:

//Create a dictionary of arguments
NSDictionary *arguments = [NSDictionary dictionaryWithObjectsAndKeys:@"'json'@", @"format@", @"'farm'", @"query", @"", @"region",@"", @"locality",@"1", @"skipcount", nil];

Licenses

The DOLData classes (whose file names start with 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.
*/

ASIHTTP

* Copyright (c) 2007-2011, All-Seeing Interactive
* 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 All-Seeing Interactive 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 All-Seeing Interactive ''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 All-Seeing Interactive 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.

A different license may apply to other software included in this package,
including GHUnit and Andrew Donoho's Reachability class. Please consult their
respective headers for the terms of their individual licenses.

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.

*/