allowances-api 0.1.0

Official Python SDK for the Allowances API

Allowances API Python SDK

The official Python client for Allowances API, a normalized API for U.S. government travel and overseas compensation data.

The API brings together rates published by three different government sources:

• DSSR — overseas post allowance (COLA), hardship differential, danger pay, education allowance, living quarters allowance, and foreign per diem.
• DTMO — military per diem for CONUS and OCONUS locations.
• GSA — civilian CONUS per diem, mileage reimbursement, and Fleet vehicle leasing rates.

This SDK handles API-key authentication, URL construction, parameter serialization, response decoding, and useful Python exceptions. It is useful for travel platforms, expense systems, payroll and mobility tools, government contractors, and internal applications that need current or historical allowance data without maintaining scrapers for several unrelated sources.

Installation

pip install allowances-api

Python 3.9 or newer is required.

Authentication

Create an API key at allowancesapi.com, then provide it directly:

from allowances_api import AllowancesClient

client = AllowancesClient("ak_live_your_key")

For applications, keeping the key in an environment variable is preferable. The client will find your api key if you set it explicitely as ALLOWANCES_API_KEY.

export ALLOWANCES_API_KEY="ak_live_your_key"

from allowances_api import AllowancesClient

client = AllowancesClient()  # reads ALLOWANCES_API_KEY

Every request sends the key in the API's X-API-Key header. Do not embed a secret API key in browser or mobile client code.

Quick start

Use the client as a context manager so its connection pool is closed automatically:

from datetime import date
from allowances_api import AllowancesClient

with AllowancesClient() as client:
    # Overseas allowances for Nairobi
    kenya = client.dssr.allowances_by_location(
        "KE",
        "Nairobi",
        date=date.today(),
        type=["cola", "hardship", "danger_pay"],
    )

    # Military OCONUS per diem
    australia = client.dtmo.perdiem_oconus("AU", query="Adelaide")

    # Civilian CONUS per diem
    albany = client.gsa.perdiem_by_state("NY", location="Albany")

Responses are returned as decoded dictionaries or lists, matching the documented JSON response exactly.

Common use cases

Look up an overseas post allowance and calculate COLA

rates = client.dssr.allowances_by_postcode("BE", "10112", types=["cola"])

estimate = client.dssr.calculate_cola(
    "10112",
    family_size=4,
    base_salary=100_000,
)
print(estimate["annual_cola"], estimate["biweekly_cola"])

Retrieve per diem by source

# Department of State foreign per diem
dssr = client.dssr.perdiem_by_location("KE", "Nairobi")

# Defense Travel Management Office military rates
dtmo = client.dtmo.perdiem_conus("US-CO", query="Aspen")

# General Services Administration civilian rates
gsa = client.gsa.perdiem_by_zipcode("12207")

Mileage and GSA Fleet rates

mileage = client.gsa.mileage(mileage_type="automobile")
fleet = client.gsa.vehicle_rates("standard", "10B", year=2026)

Browse locations

countries = client.dssr.countries(query="United")
dssr_locations = client.dssr.country_locations("DE")
dtmo_locations = client.dtmo.locations_oconus("AU", location="Sydney")
states = client.gsa.states()
destinations = client.gsa.destinations(limit=50)

Errors

The SDK maps common status codes to specific exceptions:

from allowances_api import ForbiddenError, NotFoundError, RateLimitError

try:
    result = client.dssr.perdiem("XX")
except NotFoundError as exc:
    print(exc.status_code, exc.message, exc.request_id)
except ForbiddenError:
    print("This request is not included in the current plan")
except RateLimitError:
    print("Request limit reached")

Available exception classes are AuthenticationError, ForbiddenError, NotFoundError, ValidationError, RateLimitError, TransportError, and the base AllowancesAPIError.

Configuration

Use a different endpoint or timeout for local development and testing:

client = AllowancesClient(
    "test-key",
    base_url="http://localhost:8000/v1",
    timeout=10,
)

An existing httpx.Client can be injected for custom transports, proxies, telemetry, or testing:

import httpx
from allowances_api import AllowancesClient

transport = httpx.HTTPTransport(retries=2)
http = httpx.Client(base_url="https://api.allowancesapi.com/v1", transport=transport)
client = AllowancesClient("ak_live_your_key", http_client=http)

When injecting a client, its lifecycle remains owned by the caller.

Endpoint mapping

SDK methods follow the API's three source groups:

• client.dssr: allowances, per diem, COLA calculator, countries, and locations.
• client.dtmo: CONUS/OCONUS per diem, search, and locations.
• client.gsa: destination/state/ZIP per diem, ZIP and county metadata, mileage, and vehicle rates.

See the complete API documentation for response fields, plan limits, and data-source details.

Development and publishing

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest
ruff check .
python -m build
twine check dist/*

Publish a release after updating the version in pyproject.toml and src/allowances_api/__init__.py:

twine upload dist/*

License

MIT