DigitalGov Search > APIs for Developers > Jobs API

Helping job seekers land a job with the government.

Overview

Federal, state, and local government agencies are hiring and have thousands of job openings across the country, posted on USAJobs.gov and local government jobs sites.

This Jobs API allows you to tap into a list of current jobs openings with the government. Jobs are searchable by keyword, location, agency, schedule, or any combination of these.

This API is great for job websites or applications, job banks, and career counseling and placement applications.

Using the API

The current default version of the API is v3. To explicitly specify an older version of the API, see the Jobs API code documentation.

This Jobs API accepts a GET request.

Jobs are searchable by keyword, location, agency, schedule, or any combination of these.

The base URL is https://api.usa.gov/jobs/search.json?parameters

Sample API requests follow.

All nursing jobs https://api.usa.gov/jobs/search.json?query=nursing+jobs

Nursing jobs in NY https://api.usa.gov/jobs/search.json?query=nursing+jobs+in+ny

Nursing jobs with a state government agency https://api.usa.gov/jobs/search.json?query=nursing+jobs&tags=state

Nursing jobs with a federal government agency https://api.usa.gov/jobs/search.json?query=nursing+jobs&tags=federal

Nursing jobs with Veterans Affairs in NY https://api.usa.gov/jobs/search.json?query=nursing+jobs+with+veterans+affairs+in+ny

Part-time nursing jobs with Veterans Affairs in NY https://api.usa.gov/jobs/search.json?query=parttime+nursing+jobs+with+veterans+affairs+in+ny

Parameters

Seven parameters are accepted.

  1. query
  2. organization_ids (comma-separated)
  3. hl (for highlighting)
  4. size
  5. from
  6. tags (comma-separated)
  7. lat_lon

Query

Attempts to extract as much "signal" as possible from the input text. Handles word variants, so a search on "nursing jobs" will find a job titled "nurse practitioner" and "RN." When parts of the query parameter are used to search against the position title, the results are ordered by relevance. When no query parameter is specified, they are ordered by date with the most recent listed first. For generic jobs searches (e.g., 'jobs', 'internships') where the lat_lon parameter is passed in, the results will be sorted by distance to the searcher's geographic location.

Sample query formats follow.

All jobs (by date or by proximity)

  • jobs
  • positions
  • vacancies
  • opportunities
  • postings

Location-based (by date)

  • jobs in fulton
  • jobs in fulton, md
  • jobs in fulton, maryland
  • jobs in md
  • pentagon jobs
  • jobs fayetteville
  • fayetteville nc jobs
  • jobs atlanta georgia

Agency-based (by date)

  • job opportunities at the cia
  • jobs at the treasury dept
  • tsa job openings
  • va jobs # will match jobs in Virginia

Keyword-based (by relevance)

  • nursing jobs
  • summer internship position

Schedule-based (by date)

  • part-time jobs
  • full-time positions

Combinations (by relevance)

  • part-time security guard job openings at the tsa in los angeles, ca

Organization_ids

A comma-separated string specifying which federal, state, or local agencies to use as a filter.

For federal agencies, the ID is based on USAJobs' agency schema. Two letter codes are used to span entire departments, while four letter codes are generally used for independent agencies or agencies within a department.

For state and local agencies, a sample of the format follows.

State of Virginia US-VA

State of Virginia Department of Taxation US-VA:DEPT-TAX

Fairfax County, VA US-VA:COUNTY-FAIRFAX

Fairfax County Sheriff US-VA:COUNTY-FAIRFAX:SHERIFF

City of Fairfax, VA US-VA:COUNTY-FAIRFAX:CITY-FAIRFAX

Air Force or State of Virginia AF,US-VA

If you specify organization_ids in your API call but the searcher types in another agency, the searchers' agency overrides the organization_ids parameter. For example, VA jobs are returned when you specify Air Force jobs, but the searcher looks for jobs at the VA (https://api.usa.gov/jobs/search.json?query=jobs+at+the+va&organization_ids=AF).

Hl [highlighting]

No highlighting is included by default. Use 'hl=1' to highlight terms in the position title that match terms in the user's search. Highlighted terms are surrounded with <em> tags.

Size

Specifies how many results are returned (up to 100 at a time).

From

Specifies the starting record.

Tags

A comma-separated string specifying the level of government. Current tags are federal, state, county, and city. To get federal and state listings, you would pass in federal,state for the tags parameter.

Lat_lon

Comma-separated pair denoting the position of the searcher looking for a job. For example, 'lat_lon=37.783333,-122.416667' is the value for San Francisco, CA. For generic job searches (e.g., 'jobs', 'internships') where this parameter is passed in, the Jobs API server will sort jobs results and return those that are closest to the searcher's location. For jobs that have multiple locations associated with the position, the distance to the closest location is used to determine the overall geo-distance for the job. Note that for keyword-based job searches (e.g., 'jobs in NY', 'nursing jobs'), this parameter has no effect and is ignored.

Data Sources

We've tailored this Jobs API for our use in our search results. Data are normalized across government job listings and we don't include all jobs from all data sources. So, we encourage you to use the original data sources directly.

Federal government jobs are from USAJobs. The USAJobs API for job opportunity announcements is at https://data.usajobs.gov/Rest.

State and local government jobs are from cities, counties, and state agencies that use NeoGov (External link), such as jobs with the the city of Boulder, Colorado.

Are we missing your jobs data? Email us at search@support.digitalgov.gov to let us know where you publish the jobs data for your federal, state, or local government agency. We'll accept your jobs data via FTP or any machine-readable format (such as an RSS feed or API).

What it Returns

Below is a sample JSON response for https://api.usa.gov/jobs/search.json?query=nursing+jobs+with+veterans+affairs+in+albany+ny.

[
  {
    id: "usajobs:340537800",
    position_title: "Nursing Assistant Float Pool",
    organization_name: "Veterans Affairs, Veterans Health Administration",
    rate_interval_code: "PA",
    minimum: 31315,
    maximum: 40706,
    start_date: "2013-03-27",
    end_date: "2013-05-31",
    locations: [
        "Albany, NY"
    ],
    url: "https://www.usajobs.gov/GetJob/ViewDetails/340537800"
  },
  {
    id: "usajobs:342782900",
    position_title: "Registered Nurse - Endoscopy",
    organization_name: "Veterans Affairs, Veterans Health Administration",
    rate_interval_code: "PA",
    minimum: 0,
    maximum: 0,
    start_date: "2013-05-02",
    end_date: "2013-05-13",
    locations: [
        "Albany, NY"
    ],
    url: "https://www.usajobs.gov/GetJob/ViewDetails/342782900"
  }
]

Code Samples

We "eat our own dog food" and use this Jobs API to display the job openings on the government websites that use DigitalGov Search.

See the sample results page below that shows current jobs openings across the Department of Homeland Security for a search on jobs on DHS.gov.

Open Source Code

The server code that runs this API is on Github. If you're a Rails developer, fork our Jobs Server API repo to add features (such as additional datasets) or fix bugs.

Better yet, send us a pull request to contribute your changes to our project and improve this API for everyone who is using it.

Feedback

Email us at search@support.digitalgov.gov with any suggestions about what you'd like to see in the next version of API.

Terms of Use

By accessing the Jobs API, you agree to USA.gov's Terms of Service for Developer Resources.