The Job Search endpoint 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.
GET /api/Search
API Key Authentication
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:
Keyword
Issues search to find hits based on a keyword. Optional. Keyword will search for all of the words specified (or synonyms of the word) throughout the job announcement.
https://data.usajobs.gov/api/search?Keyword=Software
PositionTitle
Issues search to find hits in the title of the job.
This is the job title - e.g. IT Specialist, Psychologist, etc. The title search will be treated as "contains" and will select all job announcements where the job title contains the value provided.
The following query will return all job announcements with "psychologist" or a synonym of psychologist in the title: https://data.usajobs.gov/api/Search?PositionTitle=Psychologist
The following query will return all job announcements with "Electrical Engineer" in the title: https://data.usajobs.gov/api/Search?PositionTitle=Electrical%20Engineer
RemunerationMinimumAmount
Issues search to find hits with the minimum salary specified.
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 with a minimum salary in the $0-$24,999 range.
https://data.usajobs.gov/api/Search?RemunerationMinimumAmount=15000
RemunerationMaximumAmount
Issues search to find hits with the maximum salary specified.
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 with a maximum salary in the $50,000-$74,999 range.
For example, combining MinSalary and MaxSalary, the following query: https://data.usajobs.gov/api/Search?RemunerationMinimumAmount=26000&RemunerationMaximumAmount=85000 - will return all job announcements where the starting and/or ending salary are between $25,000 and $99,999.
PayGradeHigh
Issues search to find hits with the maximum pay grade specified. Must be 01 through 15. This is the ending grade for the job. (Caution: Fed speak ahead but it cannot be helped.) The grade along with series is used by the Federal government to categorize and define jobs. For more information on what series and grade are, please visit: https://help.usajobs.gov/index.php/What_is_a_series_and_or_grade%3F. However, grade is also used to define salary. USAJOBS search uses grades for the General Schedule (GS) pay plan ( http://www.opm.gov/policy-data-oversight/pay-leave/salaries-wages). For jobs that use a different pay plan than the GS schedule, USAJOBS will derive the corresponding grade by using the minimum and maximum salary and the wages for the GS schedule for the Rest of the United States (for 2014, see: http//www.opm.gov/policy-data-oversight/pay-leave/salaries-wages/salary-tables/14Tables/html/RUS.aspx). For federal employees, especially those who have a GS pay plan, searching by grade is extremely useful since they would already know which grades they are or qualify for. However, for non-GS employees, searching by salary is much simpler.
https://data.usajobs.gov/api/Search?PayGradeHigh=07
PayGradeLow
Issues search to find hits with the minimum pay grade specified. Must be 01 through 15. This is the beginning grade for the job. See PayGradeHigh for more information.
https://data.usajobs.gov/api/Search?PayGradeLow=04 https://data.usajobs.gov/api/Search?PayGradeLow=07&PayGradeHigh=09
JobCategoryCode
Issues a search to find hits with the job category series specified.
See Code List for a listing of the Job Category codes.
https://data.usajobs.gov/api/Search?JobCategoryCode=0830
Note: Multiple values are semicolon delimited.
LocationName
Issues a search to find hits within the specified location. This is the city or military installation name. LocationName simplifies location based search as the user does not need to know or account for each and every Location Code. LocationName will search for all location codes and ZIP codes that have that specific description.
For example, to find all job announcements in Washington, DC, use: https://data.usajobs.gov/api/Search?LocationName=Washington%20DC,%20District%20of%20Columbia.
To find all job announcements in Atlanta, GA use: https://data.usajobs.gov/api/Search?LocationName=Atlanta,%20Georgia.
NOTE: Multiple values are semicolon delimited.
PostingChannel
Issues a search to find jobs with a posting channel specified. Posting channels are used to identify different sources for Agency reporting, and categorizing needs.
Organization
Issues a search to find jobs for the specified agency using the Agency Subelement Code. See Code List for a listing of the Organization codes.
The following will get a listing of job announcements from the Department Of The Treasury: https://data.usajobs.gov/api/Search?Organization=TR
PositionOfferingTypeCode
Issues a search to find jobs within the specified type. This field is also known as Work Type.
TravelPercentage
Issues a search to find hits for jobs matching the specified travel level. Acceptable values for travel percentage parameter are:
https://data.usajobs.gov/api/Search?TravelPercentage=0 https://data.usajobs.gov/api/Search?TravelPercentage=7
PositionScheduleTypeCode
Issues a search to find hits for jobs matching the specified job schedule. This field is also known as work schedule. Acceptable values for Position Schedule Type Code are:
https://data.usajobs.gov/api/Search?PositionSchedule=4
RelocationIndicator
Issues a search to find hits for jobs matching the relocation filter. Acceptable values for this field are: True or False
SecurityClearanceRequired
Issues a search to find hits for jobs matching the specified security clearance. Acceptable values for Security Clearance Required parameter are:
https://data.usajobs.gov/api/Search?SecurityClearanceRequired=1
SupervisoryStatus
Issues a search to find hits for jobs matching the specified supervisory status.
DatePosted
Issues a search to find hits for jobs that were posted within the number of days specified.Acceptable values for DatePosted are integers in the range of 0 - 60.
JobGradeCode
Issues a search to find hits for jobs matching the grade code specified. This field is also known as Pay Plan.
SortField
Issues a search that will be sorted by the specified field. Acceptable values for Sort Field parameter are:
https://data.usajobs.gov/api/Search?PositionTitle=Electrical&SortField=PositionTitle
SortDirection
Issues a search that will be sorted by the SortField specified, in the direction specified. Asc for ascending, or desc for descending.
https://data.usajobs.gov/api/Search?PositionTitle=Electrical&SortField=PositionTitle&SortDirection=Asc
Page
Issues a search to pull the paged results specified.
ResultsPerPage
Issues a search and returns the page size specified. In this example, 25 jobs will be return for the first page. Acceptable values for this field are numbers, up to 500.
https://data.usajobs.gov/api/Search?ResultsPerPage=50
WhoMayApply
Issues a search to find hits based on the desired candidate designation. In this case, public will find jobs that U.S. citizens can apply for. Acceptable values for this parameter are: "All","Public", or "Status".
https://data.usajobs.gov/api/Search?WhoMayApply=public
NOTE: All and Status require specific authorization.
Radius
Issues a search when used along with LocationName, will expand the locations, based on the radius specified.
https://data.usajobs.gov/api/Search?LocationName=Norfolk%20Virginia&Radius=75
Fields
Issues a search that will return the minimum fields or maximum number of fields in the job. Min returns only the job summary. Acceptable values for this field are: "Min" and "Full"
https://data.usajobs.gov/api/Search?TravelPercentage=7&Fields=full https://data.usajobs.gov/api/Search?SecurityClearanceRequired=1&Fields=full
SalaryBucket
Issues a search that will find hits for salaries matching the grouping specified. Buckets are assigned based on salary ranges. For example 25 = $25,000-$49,000.
GradeBucket
Issues a search that will find hits for grades that match the grouping specified.
HiringPath
Issues a search that will find hits for hiring paths that match the hiring paths specified.
https://data.usajobs.gov/api/Search?HiringPath=public
MissionCriticalTags
Issues a search that will find hits for mission critical tags that match the grouping specified.
https://data.usajobs.gov/api/Search?MissionCriticalTags=STEM&Fields=full
PositionSensitivity
Issues a search that will find hits for jobs matching the position sensitivity and risk specified. Acceptable values for Position Sensitivity and Risk parameter are:
https://data.usajobs.gov/api/Search?PositionSensitivity=1
RemoteIndicator
Issues a search to find hits for jobs matching the remote filter. Acceptable values for this field are: True (only Remote jobs will be returned) or False (excludes Remote jobs).
NOTE: If the RemoteIndicator is not passed then Remote jobs will be included in results, by default.
An example using multiple parameters: https://data.usajobs.gov/api/Search?Keyword=nurse&JobCategoryCode=2210&WhoMayApply=public&fields=all
PostChannelID (PCI) is used within USAJOBS to identify the source from which a job seeker originates.
JSON: { "LanguageCode": "EN", "SearchParameters": {}, "SearchResult": { "SearchResultCount": 25, "SearchResultCountAll": 100, "SearchResultItems": [ { "MatchedObjectId": "21947200", "MatchedObjectDescriptor": { "PositionID": "SW62210-05-1716110PB411413H", "PositionTitle": "IT SPECIALIST (INFOSEC/NETWORK)", "PositionURI": "https://www.usajobs.gov/GetJob/ViewDetails/21947200", "ApplyURI": [ "https://www.usajobs.gov/GetJob/ViewDetails/21947200?PostingChannelID=RESTAPI" ], "PositionLocationDisplay": "Point Loma Complex, San Diego, California", "PositionLocation": [ { "LocationName": "Point Loma Complex, San Diego, California", "CountryCode": "United States", "CountrySubDivisionCode": "California", "CityName": "Point Loma Complex, San Diego, California", "Longitude": -117.194382, "Latitude": 32.7042961 } ], "OrganizationName": "Space and Naval Warfare Systems Command", "DepartmentName": "Department of the Navy", "JobCategory": [ { "Name": "Information Technology", "Code": "2200" }, { "Name": "Information Technology Management", "Code": "2210" } ], "JobGrade": [ { "Code": "NO" } ], "PositionSchedule": [ { "Name": "Full Time", "Code": "1" } ], "PositionOfferingType": [ { "Name": "Permanent", "Code": "15317" } ], "QualificationSummary": "...", "PositionRemuneration": [ { "MinimumRange": "92108", "MaximumRange": "119746", "RateIntervalCode": "PA", "Description": "Per Year" } ], "PositionStartDate": "2016-06-05T00:00:00Z", "PositionEndDate": "2016-12-01T00:00:00Z", "PublicationStartDate": "2016-06-05T00:00:00Z", "ApplicationCloseDate": "2016-12-01T00:00:00Z", "PositionFormattedDescription": [ { "Content": "This announcement is being used to recruit qualified individuals, under the Office of Personnel Management (OPM) Direct Hire Authority, authorized by 5 United States Code (U.S.C.), Section 3304 and 5 Code of Federal Regulations (CFR) Part 337, Subpart B. The Rule of Three, Veteran's Preference and t", "Label": "Dynamic Teaser", "LabelDescription": "Hit highlighting for keyword searches." } ], "UserArea": { "Details": { "MajorDuties": "Major Duties and Responsibilities: ...", "Education": "EDUCATION: ...", "Requirements": "", "Evaluations": "...", "HowToApply": "...", "WhatToExpectNext": "...", "RequiredDocuments": "...", "Benefits": "...", "BenefitsUrl": "", "OtherInformation": "...", "KeyRequirements": [], "JobSummary": "...", "WhoMayApply": { "Name": "United States Citizens", "Code": "15514" }, "LowGrade": "05", "HighGrade": "05", "SubAgencyName": "Space and Naval Warfare System Command Pacific", "OrganizationCodes": "DD/NV/NV39" }, "IsRadialSearch": false } }, "RelevanceRank": 0.0 } ], "UserArea": { "Refiners": { "Organization": [ { "RefinementName": "AG/AG02", "RefinementCount": "1", "RefinementToken": "^AG/AG02$", "RefinementValue": "AG/AG02" } ], "GradeBucket": [ { "RefinementName": "12", "RefinementCount": "46", "RefinementToken": "^12$", "RefinementValue": "12" } ], "SalaryBucket": [ { "RefinementName": "75", "RefinementCount": "80", "RefinementToken": "^75$", "RefinementValue": "75" } ], "PositionOfferingTypeCode": [ { "RefinementName": "15317", "RefinementCount": "86", "RefinementToken": "15317", "RefinementValue": "15317" } ], "PositionScheduleTypeCode": [ { "RefinementName": "1", "RefinementCount": "100", "RefinementToken": "1", "RefinementValue": "1" } ], "JobCategoryCode": [ { "RefinementName": "2200/2210", "RefinementCount": "100", "RefinementToken": "^2200/2210$", "RefinementValue": "2200/2210" } ] }, "NumberOfPages": "4", "IsRadialSearch": false } } }
{ "LanguageCode": "EN", "SearchParameters": {}, "SearchResult": { "SearchResultCount": 25, "SearchResultCountAll": 100, "SearchResultItems": [ { "MatchedObjectId": "21947200", "MatchedObjectDescriptor": { "PositionID": "SW62210-05-1716110PB411413H", "PositionTitle": "IT SPECIALIST (INFOSEC/NETWORK)", "PositionURI": "https://www.usajobs.gov/GetJob/ViewDetails/21947200", "ApplyURI": [ "https://www.usajobs.gov/GetJob/ViewDetails/21947200?PostingChannelID=RESTAPI" ], "PositionLocationDisplay": "Point Loma Complex, San Diego, California", "PositionLocation": [ { "LocationName": "Point Loma Complex, San Diego, California", "CountryCode": "United States", "CountrySubDivisionCode": "California", "CityName": "Point Loma Complex, San Diego, California", "Longitude": -117.194382, "Latitude": 32.7042961 } ], "OrganizationName": "Space and Naval Warfare Systems Command", "DepartmentName": "Department of the Navy", "JobCategory": [ { "Name": "Information Technology", "Code": "2200" }, { "Name": "Information Technology Management", "Code": "2210" } ], "JobGrade": [ { "Code": "NO" } ], "PositionSchedule": [ { "Name": "Full Time", "Code": "1" } ], "PositionOfferingType": [ { "Name": "Permanent", "Code": "15317" } ], "QualificationSummary": "...", "PositionRemuneration": [ { "MinimumRange": "92108", "MaximumRange": "119746", "RateIntervalCode": "PA", "Description": "Per Year" } ], "PositionStartDate": "2016-06-05T00:00:00Z", "PositionEndDate": "2016-12-01T00:00:00Z", "PublicationStartDate": "2016-06-05T00:00:00Z", "ApplicationCloseDate": "2016-12-01T00:00:00Z", "PositionFormattedDescription": [ { "Content": "This announcement is being used to recruit qualified individuals, under the Office of Personnel Management (OPM) Direct Hire Authority, authorized by 5 United States Code (U.S.C.), Section 3304 and 5 Code of Federal Regulations (CFR) Part 337, Subpart B. The Rule of Three, Veteran's Preference and t", "Label": "Dynamic Teaser", "LabelDescription": "Hit highlighting for keyword searches." } ], "UserArea": { "Details": { "MajorDuties": "Major Duties and Responsibilities: ...", "Education": "EDUCATION: ...", "Requirements": "", "Evaluations": "...", "HowToApply": "...", "WhatToExpectNext": "...", "RequiredDocuments": "...", "Benefits": "...", "BenefitsUrl": "", "OtherInformation": "...", "KeyRequirements": [], "JobSummary": "...", "WhoMayApply": { "Name": "United States Citizens", "Code": "15514" }, "LowGrade": "05", "HighGrade": "05", "SubAgencyName": "Space and Naval Warfare System Command Pacific", "OrganizationCodes": "DD/NV/NV39" }, "IsRadialSearch": false } }, "RelevanceRank": 0.0 } ], "UserArea": { "Refiners": { "Organization": [ { "RefinementName": "AG/AG02", "RefinementCount": "1", "RefinementToken": "^AG/AG02$", "RefinementValue": "AG/AG02" } ], "GradeBucket": [ { "RefinementName": "12", "RefinementCount": "46", "RefinementToken": "^12$", "RefinementValue": "12" } ], "SalaryBucket": [ { "RefinementName": "75", "RefinementCount": "80", "RefinementToken": "^75$", "RefinementValue": "75" } ], "PositionOfferingTypeCode": [ { "RefinementName": "15317", "RefinementCount": "86", "RefinementToken": "15317", "RefinementValue": "15317" } ], "PositionScheduleTypeCode": [ { "RefinementName": "1", "RefinementCount": "100", "RefinementToken": "1", "RefinementValue": "1" } ], "JobCategoryCode": [ { "RefinementName": "2200/2210", "RefinementCount": "100", "RefinementToken": "^2200/2210$", "RefinementValue": "2200/2210" } ] }, "NumberOfPages": "4", "IsRadialSearch": false } } }
As a USAJOBS API Consumer, you agree to the following terms and conditions, and any policies, guidelines or amendments thereto that may be presented to you from time to time (collectively, the "Terms of Service") governing use of the USAJOBS API service. The Office of Personnel Management USAJOBS Program Office (OPM USAJOBS) may update the Terms of Service, and will notify you by email to accept the most current version of the Terms of Service. Inquiries should be sent via email: access@usajobs.gov
The API is described on the USAJOBS Developer site available here: https://developer.usajobs.gov. in consideration of your use of the api, you may be required to provide current, accurate identification, contact, and other information as part of the registration process and />or continued use of the services offered by OPM USAJOBS and its representatives. You are responsible for maintaining the confidentiality of your USAJOBS API key, and are responsible for all activities that occur under your account. You agree to immediately notify USAJOBS of any unauthorized use of your API key or any other breach of security. USAJOBS cannot and will not be liable for any loss or damage arising from your failure to comply with this.
USAJOBS reserves the right to refuse service to anyone at any time found to be in violation of this and subsequent sections. USAJOBS reserves the right at any time and from time to time to modify or discontinue, temporarily or permanently, the API (or any part thereof) with or without notice. You agree that USAJOBS shall not be liable to you or to any third party for any modification, suspension or discontinuance of USAJOBS services.
Data provided to you through the API is for the explicit use of the requesting company identified on the USAJOBS Program Office API Registration Form. No other use of the data provided is permitted without prior approval, in writing, from OPM USAJOBS. You may not rent, lease, loan, sell, trade or create derivative works of USAJOBS API services and data, in whole or in part.
The data provided through the API is restricted to publicly available information found in a USAJOBS JOA, contains no Personally-Identifiable Information (PII) of USAJOBS system users other than publicly disclosed contact information within the JOA, and may not exceed the Controlled Unclassified Information (CUI) designation.
You agree that you are responsible for your own conduct and the proper handling of any information made available while using the API and for any consequences thereof. You agree to use the API only for purposes that are legal, proper and in accordance with these Terms of Service and any applicable policies or guidelines. By way of example, and not as a limitation, you agree that when using the USAJOBS API, you will not:
You understand and agree that USAJOBS shall have the right (but not the obligation) in its sole discretion to deny access to those users that are found to be in violation of these Terms of Service.
By using the USAJOBS API service, you acknowledge and agree that OPM USAJOBS may access, preserve, and disclose your API account information or information about account activity if required to do so by law or in a good faith belief that such access preservation or disclosure is reasonably necessary to: (a) satisfy any applicable law, regulation, legal process or governmental request, (b) enforce this Terms of Service, including investigation of potential violations hereof, (c) detect, prevent, or otherwise address fraud, security or technical issues, (d) respond to JOA Consumer support requests, or (e) protect the rights, property or safety of USAJOBS, its users and the public. USAJOBS will not be responsible or liable for the exercise or non- exercise of its rights under the Terms of Service.
You understand that the technical processing and transmission of USAJOBS services, including API information, may involve (a) transmissions over various networks; and (b) changes to conform and adapt to technical requirements of connecting networks or devices.
You agree that OPM USAJOBS has no responsibility or liability for the deletion or failure to store any API service data. You acknowledge that OPM USAJOBS retains the right, at its sole discretion, to create limits at any time with or without notice on the number of API transactions the API Consumer may initiate, the size of API data files received, or the amount of storage space used.
You may cancel your use of the API with or without cause at any time by providing notice to USAJOBS at access@usajobs.gov; provided, however, that a terminated account may continue to exist until processed for removal and deletion under standard account management procedures. USAJOBS may at any time and for any reason, including a period of account inactivity, terminate your access. In the event of termination, your API key will be disabled and you may not be granted access to your API information.
API data may include links to World Wide Web sites or resources external to the USAJOBS information system. You acknowledge and agree that OPM is not responsible for the availability of such external sites or resources, and does not endorse and is not responsible or liable for any content available from such sites or resources, or your use or reliance on or through these resources.
You agree to hold harmless and indemnify USAJOBS, and its subsidiaries, affiliates, officers, agents, and employees, from and against any third party claim arising from or in any way related to your use of the API or violation of these Terms of Service including any liability or expense arising from all claims, losses, damages (actual and consequential), suits, judgments, litigation costs and attorneys' fees, of every kind and nature. In such a case, USAJOBS will provide you with written notice of such claim, suit or action.
You expressly understand and agree that USAJOBS shall not be liable to you for any direct, indirect, incidental, special, consequential or exemplary damages resulting from: (i) the use or the inability to use the API; (ii) the cost of procurement of substitute goods and services resulting from any goods, data, information or services purchased or obtained or messages received or transactions entered into through or from the API; (iii) unauthorized access to or alteration of your transmissions or data; (iv) statements or conduct of any third party utilizing the API; or (v) any other matter relating to OPM USAJOBS.
Any material downloaded or otherwise obtained through the use of the API is done at your own discretion and risk and that you will be solely responsible for any damage to your computer system or loss of data that results from the download of any such material.
No advice or information, whether oral or written, obtained by you from OPM shall create any warranty.
You agree that there shall be no third party beneficiaries to the Terms of Service.
The Terms of Service constitute the entire agreement between you and OPM governing your use of the USAJOBS API service as an API Consumer. You also may be subject to additional terms and conditions that may apply when you use other USAJOBS services.
The failure of USAJOBS to exercise or enforce any right or provision of the Terms of Service shall not constitute a waiver of such right or provision.
An official website of the United States Government
An official website of the United States Government