Job Opportunity Announcements (JOA)

Introduction

The REST based API is designed to support lightweight JOA content consumption by consumers. It is anticipated that this API will be leveraged by Commercial Job Boards, Mobile Applications and Social Media sites who desire to provide employment opportunities on their site. Typically in these commercial venues, the breadth of data presented to a user (job seeker) is much smaller than the detailed content provided on USAJOBS, as required by law.

Technical Overview

  1. The REST API does not require authentication and is open to all consumers.
  2. The data presented back through the API is for Public Job Opportunities. These jobs are open to the public.
  3. The API will provide a maximum of 5,000 job results per query. The API will leverage paging to return the results in groups of 250 JOAs per page.

Technical Implementation Detail

To instantiate the REST API, an HTTPS GET will be used. All interactions with USAJOBS are via HTTPS.

  1. It will require that you provide the base URL: https://data.usajobs.gov/api/jobs
    With the base URL, you will append the query parameters to drive the results outcome desired. In the below example, the query parameter for occupational series is included to select all jobs for Information Technology Management.

    https://data.usajobs.gov/api/jobs?series=2210

  2. Request Header
    • Host: data.usajobs.gov
    • Within the Request Header, you also need to identify which format you desire. JSON is the default value if not specified:
      1. Content-type: application/json
      2. Content-type: application/xml
  1. As noted in the previous Tab (Instantiating the API), the query parameters are appended to the URL to drive the specific results desired. Each consumer can leverage any combination of these parameters. The query parameters are:

    Data Element Description
    OrganizationID Example AF for all Air Force or HE39 for CDC
    Title Specific Title Search – Assumes that title contains the text provided
    Series 0602 would select only doctors
    MinSalary Jobs are placed in salary buckets: $0-$24,999, $25,000-$49,999, $50,000-$74,999, $75,000-$99,999, $100,000-$124,999, $125,000-$149,999, $150,000-$174,999, $175,000-$199,999 and $200,000 or greater. So a search with a minimum salary of $15,500 will return jobs in the $0-$24,999 range.
    MaxSalary Jobs are placed in salary buckets: $0-$24,999, $25,000-$49,999, $50,000-$74,999, $75,000-$99,999, $100,000-$124,999, $125,000-$149,999, $150,000-$174,999, $175,000-$199,999 and $200,000 or greater. So a search with a maximum salary of $72,000 will return jobs in the $50,000-$74,999 range.
    LocationID This is the zip code or the geo location code. Valid zip codes and geo location codes can be found on https://schemas.usajobs.gov.
    LocationName City or Military Installation Name (e.g., Philadelphia)
    Country Country name - e.g. United States. A valid list of country names can be found on https://schemas.usajobs.gov.
    CountrySubDivision State name - e.g. Georgia.
    SES Yes/No – Default is No
    GradeLow Must be 01 through 15
    GradeHigh Must be 01 through 15
    Keyword Optional
    Student Yes/No – Default is No
    Page Used to identify the Page Number associated to the returned results set
    NumberOfJobs Used to identify the number of results to return when calling the API. Must be an integer between 1 and 250. If not specified, 25 is the default.
  2. When leveraging the different Query Parameters, there are some basic rules of how to best leverage each parameter to drive the best results. They are:
    • Multiple values need to be separated by a semicolon.
    • CountrySubDivision & Country should be the full name defined in the enumeration tables on the Schema Site (reference schemas.usajobs.gov). For example: France for country or Virginia for CountrySubDivision
    • LocationID will support the 9-character Duty Station codes or Zip Codes. NOTE: Use of Location ID will only return JOAs posted those specific codes. If you are unfamiliar with these codes, they are available on schemas.usajobs.gov. You may alternatively use Location Name, CountrySubDivision and Country to drive your results without referencing the LocationID.
    • LocationName will search for all location codes and ZIP codes that have that specific description. LocationName simplifies location based search as the user does not need to know or account for each and every code. As example, Washington DC has over 200 zip codes and 7 different Duty Station codes. If the consumer wishes to find all JOAs posted to Washington DC, they should use LocationName instead of LocationID.
    • Country and CountrySubDivision will be ignored if a LocationID is sent.
    • GradeLow and GradeHigh must be values 01 through 15.
    • If a Title is included, it will be treated as contains and will select all JOAs where the JOA title contains the value provided.
    • If Student is included with a value of Yes, only Student JOAs will be returned. The default value is No.
    • If SES in included with a value of Yes, only SES JOAs will be returned. The default value is No.
    • Page. The Page query parameter is used to specify which page results are desired. The API can provide up to 5,000 results for a given query. Within those results, the Page parameter is leveraged to return the specific results for that page. The Page parameter ensures that results are returned quickly and don’t impede performance with the consumers presentation layer.
    • NumberOfJobs. The NumberOfJobs query parameter is used to specify the number of jobs to return per query. The maximum value is 250. The default value is 25. This will directly affect the total number of jobs return value and the page parameter. So it should be specified on every call if not using the default value.
  3. An example of the URL leveraging multiple query parameters would be:

    https://data.usajobs.gov/api/jobs?OrganizationID=DD;HE39&series=2210&LocationName=Reston&CountrySubDivision=Virginia&Page=2

    In this example, the API Query would return JOAs that belong to DoD or CDC, have an occupational series of 2210 (computer oriented positions), located in Reston, Virginia, for the 2nd page of the results.
PostChannelID (PCI) is used within USAJOBS to identify the source from which a job seeker originates.

  • The default PostChannelID of RESTAPI will be generated in the ApplyOnlineURL node within the data returned for each JOA.
  • If you have previously requested and been provided a PCI, you would simply replace RESTAPI with your PCI. Why is this important? As USAJOBS runs sourcing analysis reports, it identifies that the job seeker originated at a specific JOA consumers site. Over time, this provides not only USAJOBS, but also the agencies clear transparency to venues that attract the Federal Job Seekers.
  • If you would like to have a PostChannelID established for Sourcing Analysis, please submit your request to recruiter-help@usajobs.gov. We will need your Company Name, Site Name, and technical contact information.
As noted previously, the REST API can render results to you in both JSON and XML format. The following examples are provided:

  1. JSON Sample Output:

    {"TotalJobs":"1","JobData":[{"DocumentID":"12951900","JobTitle":"Information Technology Specialist (Systems Analysis), GS-2210-12/13", "OrganizationName":"Department Of Health And Human Services", "AgencySubElement":"Office of the Secretary of Health and Human Services", "SalaryMin":"$74,872.00","SalaryMax":"$115,742.00","SalaryBasis":"Per Year", "StartDate":"2/16/2013","EndDate":"12/31/2013", "WhoMayApplyText":"United States Citizens","PayPlan":"GS","Series":"2210", "Grade":"12/13","WorkType":"Career/Career Conditional", "WorkSchedule":"Full Time","Locations":"Washington DC Metro Area, District of Columbia","AnnouncementNumber":"HHS-OS-DE-11-440116", "JobSummary":"This position is located in the Department of Health and Human Services (HHS), Office of the Secretary (OS), Assistant Secretary for Administration (ASA), Office of Human Resources, Enterprise Systems Division in Washington, D.C. This vacancy is also being announced concurrently with vacancy announc", "ApplyOnlineURL":"https://www.usajobs.gov/GetJob/ViewDetails/12951900?PostingChannelID=RESTAPI"},],"Pages":"1"}

  2. XML Sample Output:

As defined in both of the examples provided, the ApplyOnlineURL node will redirect a job seeker from the consumer’s site to USAJOBS. The job seeker can review the JOA in more detail or apply for the job opportunity. If you have a PostChannelID established, please replace "RESTAPI" with your specific PostChannelID.
For questions or assistance in leveraging the API, please contact USAJOBS at recruiter-help@usajobs.gov. When you submit a question or request to this email address, a ticket will automatically be opened and routed to the resources that can best assist.