Skip to main content

A Python wrapper for the USA Jobs REST API.

Project description

python-usajobsapi

PyPI License Tests Code Style Coverage Status

python-usajobsapi is a typed Python wrapper for the USAJOBS REST API. The project provides a clean interface for discovering and querying job postings using Python.

Status

This project is under active development and its API may change. Changes to the USAJOBS REST API documentation are monitored and incorporated on a best-effort basis. Feedback and ideas are appreciated.

Overview

The USAJOBS REST API exposes a large catalog of job opportunity announcements (JOAs) with a complex query surface. This project focuses on providing:

  • Declarative endpoint definitions.
  • Strongly typed request/query parameters and response models.
  • Streaming helpers for paginating through large result sets.
  • Normalization of data formats (e.g., date handling, booleans, payload serialization).

Supported Endpoints

This package primarily aims to support searching and retrieval of active and past job listings. Coverage of all documented endpoints will continue to be expanded.

Currently, the following endpoints are supported:

Installation

From PyPI

pip install python-usajobsapi

or, with astral-uv:

uv add python-usajobsapi

From source

git clone https://github.com/your-username/python-usajobsapi.git
cd python-usajobsapi
pip install .

Quickstart

  1. Request USAJOBS API credentials (Job Search API only).
  2. Instatiate the client (USAJobsClient) with your User-Agent (email) and API key.
  3. Perform a search:
from usajobsapi import USAJobsClient

client = USAJobsClient(auth_user="name@example.com", auth_key="YOUR_API_KEY")
response = client.search_jobs(keyword="data scientist", location_names=["Atlanta", "Georgia"])

for job in response.jobs():
    print(job.position_title)

Pagination

Handling pagination

Use streaming helpers to to iterate through multiple pages or individual result items without needing to worry about pagination:

for job in client.search_jobs_items(keyword="cybersecurity", results_per_page=100):
    if "Remote" in (job.position_location_display or ""):
        print(job.position_title, job.organization_name)

Command Line Interface

You can call the package as an executable using the usajobsapi command. Run usajobsapi --help to see the exposed arguments.

The first argument maps to a specific endpoint:

Action USAJOBS REST API Endpoint
announcementtext Announcement Text /api/historicjoa/announcementtext
search Job Search /api/search
historicjoa Historic JOA `/api/historicjoa

Query parameters are supplied with -d/--data as a JSON object:

usajobsapi search \
  --user-agent "you@example.com" \
  --auth-key "$USAJOBS_API_KEY" \
  -d '{"keyword": "data scientist", "results_per_page": 5}'

Developer Guide

Set up a development environment with uv:

uv sync --all-extras --all-groups
uv run pytest tests
uv run ruff check
uv run ruff format

Key Development Principles

  • Keep Pydantic models exhaustive and prefer descriptive field metadata so that auto-generated docs remain informative.
  • Maintain 100% passing tests, at least 80% test coverage, formatting, and linting before opening a pull request.
  • Update docstrings alongside code changes to keep the generated reference accurate.

Document Generation

Documentation is generated using MkDocs. The technical reference surfaces the reStructuredText style docstrings from the package's source code.

uv sync --group docs

# Run the development server
uv run mkdocs serve -f mkdocs/mkdocs.yaml
# Build the static site
uv run mkdocs build -f mkdocs/mkdocs.yaml

Contributing

Contributions are welcome! To get started:

  1. Fork the repository and create a new branch.
  2. Install development dependencies (see the developer guide).
  3. Add or update tests together with your change.
  4. Run the full test, linting, and formatting suite locally.
  5. Submit a pull request describing your changes and referencing any relevant issues.

For major changes, open an issue first to discuss your proposal.

Design

The software design architecture prioritizes composability and strong typing, ensuring that it is straightforward to add/update endpoints and generate documentation from docstrings.

  • Client session management: USAJobsClient wraps a configurable requests.Session to reuse connections and centralize authentication headers.
  • Declarative endpoints: Each USAJOBS endpoint is expressed as a Pydantic model with nested Params and Response classes, providing validation, serialization helpers, and rich metadata for documentation.
  • Pagination helpers: Iterators (search_jobs_pages and search_jobs_items) encapsulate pagination logic and expose idiomatic Python iterators so users focus on data consumption, not page math.
  • Shared utilities: Shared utilities handle API-specific normalization (e.g., date parsing, alias mapping) so endpoint models stay declarative and thin.

License

Distributed under the GNU General Public License v3.0. See LICENSE for details.

Contact

Questions or issues? Please open an issue on the repository's issue tracker.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_usajobsapi-1.0.1.tar.gz (121.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

python_usajobsapi-1.0.1-py3-none-any.whl (46.9 kB view details)

Uploaded Python 3

File details

Details for the file python_usajobsapi-1.0.1.tar.gz.

File metadata

  • Download URL: python_usajobsapi-1.0.1.tar.gz
  • Upload date:
  • Size: 121.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for python_usajobsapi-1.0.1.tar.gz
Algorithm Hash digest
SHA256 9a3806fb8c79897a7e8baaf1b309bba1b9889b22632d3ad7e3a0e73e44563673
MD5 c0bd610a2d038a77b2e9d8f3e8eda6d8
BLAKE2b-256 c4c6e04b4f66613fc483adaa356c8071cf9138f582b92471d0a7af55c22ea533

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_usajobsapi-1.0.1.tar.gz:

Publisher: release.yaml on paddy74/python-usajobsapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_usajobsapi-1.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for python_usajobsapi-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 113de072c90e127c2349f09ed419ca22f27e1fc21d84ee74158449839eeeb687
MD5 eb910f805165e593a237ebd53117fc8c
BLAKE2b-256 438caf3c857515515643b254c09673c845a10e40044416d40471d67fc4940aa1

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_usajobsapi-1.0.1-py3-none-any.whl:

Publisher: release.yaml on paddy74/python-usajobsapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page