USAJobs Vacancy Finder 🇺🇸🔍

A hybrid CLI tool and Python extractor for USAJobs.gov designed to quickly find, filter, and extract federal job openings with multiple/MANY vacancies, rich metadata (GS grade, security clearance, telework/remote status, financial disclosure requirements), and structured export formats (CSV/JSON/CLI).

---

💡 Why This Tool?

The official USAJobs web UI and search API do not provide a structured filter for vacancy count. Key details like whether a listing has "Many vacancies" or "Multiple positions" are buried inside individual job announcement detail pages.

usajobs-vacancy-finder bridges this gap using a hybrid approach:

1. Official REST API: Queries https://data.usajobs.gov/api/Search for fast search, salary buckets, GS grades, clearance levels, telework/remote flags, and financial disclosure requirements.
2. Targeted Scraping: Inspects job detail pages in parallel (ThreadPoolExecutor) only when vacancy count information is absent from the API payload.

---

✨ Features

• 🎯 Filter by High Vacancies: Isolate listings with "Many", "Multiple", "Several", or numeric vacancy counts.
• 🔓 Public Eligibility Filtering: Default searches are scoped to Open to the Public (HiringPath=public).
• 💼 Rich Metadata Extraction:
  • Exact GS Grade range (GS-11/15, GS-14/15)
  • Salary ranges and pay interval
  • Security Clearance requirement (Secret, Top Secret, Public Trust, Not Required)
  • Telework and Remote eligibility
  • Financial Disclosure requirement (Yes / No)
• 📁 Export Formats: Output to interactive CLI, structured CSV, or JSON.
• ⚡ Multi-threaded Performance: Concurrent detail page fetching with configurable worker counts.

---

🛠️ Installation & Setup

1. Clone the repository

git clone https://github.com/fayerman-source/usajobs-vacancy-finder.git
cd usajobs-vacancy-finder

2. Install dependencies

pip install -r requirements.txt

3. Configure API Credentials

Obtain a free, instant USAJobs API key at developer.usajobs.gov.

Create a .env file in the project root:

cp .env.example .env

Edit .env to include your credentials:

USAJOBS_API_KEY=your_api_key_here
USAJOBS_EMAIL=your_registered_email@example.com

---

🚀 Usage Examples

Basic CLI Search

Search for public Attorney jobs:

python3 usajobs_extractor.py -k attorney

Location-Specific Search

Search for Contract Specialist positions in New York:

python3 usajobs_extractor.py -k "Contract Specialist" -l "New York, New York"

Include All Vacancy Counts

View all matching jobs (not just those flagged as "MANY"):

python3 usajobs_extractor.py -k compliance --all-vacancies

Export to CSV or JSON

Save results to a CSV spreadsheet:

python3 usajobs_extractor.py -k attorney -o csv --file attorney_listings.csv

Save results to a JSON file:

python3 usajobs_extractor.py -k "Policy Analyst" -o json --file policy_jobs.json

---

📖 CLI Arguments Reference

Option	Description	Default
-k, --keyword	Search keyword	attorney
-l, --location	Location filter string	"" (Nationwide)
-p, --pages	Number of API pages to fetch (100 jobs/page)	1
-w, --workers	Concurrent worker threads	10
-o, --output	Output mode (cli, json, csv)	cli
--file	Filename to save JSON or CSV output	None
--all-vacancies	Include all listings (not just "MANY")	False
--api-key	USAJobs API Key (overrides .env)	None
--email	Registered email for User-Agent (overrides .env)	None

---

⚖️ Legal & ToS Disclaimer

This tool uses the official USAJobs REST API provided by the U.S. Office of Personnel Management (OPM) for primary searching and metadata retrieval. Scraping is used solely to extract public vacancy count strings not returned by the API.

This project is for personal educational and job-search assistance purposes. Please respect USAJobs.gov rate limits and terms of service.

---

📜 License

Distributed under the MIT License.