DigitalGov Search > APIs for Developers > Jobs API

Fork me on GitHub

Helping job seekers land a job with the government.

  • Overview
  • Using the API
  • Parameters
  • Data Sources
  • What it Returns
  • Code Samples

    Overview

    The unemployment rate has hovered around 8 percent since early 2012. So, not surprisingly, many people are hitting the web to search for jobs.

    Federal, state, and local government agencies are hiring and have thousands of job openings across the country.

    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

    This Jobs API accepts a GET request.

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

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

    Sample API requests follow.

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

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

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

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

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

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

    Parameters

    Seven parameters are accepted.

    1. query
    2. organization_id
    3. hl (for highlighting)
    4. size
    5. from
    6. tags
    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_id

    Specifies which federal, state, or local agency 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

    If you specify an organization_id in your API call but the searcher types in another agency, the searchers' agency overrides the organization_id parameter. For example, VA jobs are returned when you specify Air Force jobs, but the searcher looks for jobs at the VA (http://api.usa.gov/jobs/search.json?query=jobs+at+the+va&organization_id=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

    Specifies the level of government. Current tags are federal, state, county, and city.

    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 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 http://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 security jobs on DHS.gov.

    Jobs GovBox 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.