allowances-api 0.1.0__py3-none-any.whl

allowances_api/__init__.py

@@ -0,0 +1,26 @@
+"""Python SDK for the Allowances API."""
+
+from .client import AllowancesClient
+from .exceptions import (
+    AllowancesAPIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    TransportError,
+    ValidationError,
+)
+
+__all__ = [
+    "AllowancesClient",
+    "AllowancesAPIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "TransportError",
+    "ValidationError",
+]
+
+__version__ = "0.1.0"
+

allowances_api/_utils.py

@@ -0,0 +1,24 @@
+from datetime import date, datetime
+from enum import Enum
+from typing import Any, Dict, Mapping, Optional
+
+
+def serialize(value: Any) -> Any:
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, (list, tuple, set)):
+        return [serialize(item) for item in value]
+    return value
+
+
+def query_params(**values: Any) -> Dict[str, Any]:
+    return {key: serialize(value) for key, value in values.items() if value is not None}
+
+
+def merge_params(params: Optional[Mapping[str, Any]], **values: Any) -> Dict[str, Any]:
+    merged = dict(params or {})
+    merged.update(query_params(**values))
+    return merged
+

allowances_api/client.py

@@ -0,0 +1,100 @@
+"""HTTP client and authentication for the Allowances API."""
+
+import os
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from .exceptions import (
+    AllowancesAPIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    TransportError,
+    ValidationError,
+    error_details,
+)
+from .resources import DSSRResource, DTMOResource, GSAResource
+
+DEFAULT_BASE_URL = "https://api.allowancesapi.com/v1"
+
+
+class AllowancesClient:
+    """Authenticated synchronous client for all public Allowances API endpoints."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        key = api_key or os.getenv("ALLOWANCES_API_KEY")
+        if not key:
+            raise ValueError("Pass api_key or set the ALLOWANCES_API_KEY environment variable")
+
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={"X-API-Key": key, "User-Agent": "allowances-api-python/0.1.0"},
+        )
+        if http_client is not None:
+            self._http.headers["X-API-Key"] = key
+            self._http.headers.setdefault("User-Agent", "allowances-api-python/0.1.0")
+
+        self.dssr = DSSRResource(self)
+        self.dtmo = DTMOResource(self)
+        self.gsa = GSAResource(self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        try:
+            response = self._http.request(method, path, params=params)
+        except httpx.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+
+        if response.is_success:
+            if response.status_code == 204 or not response.content:
+                return None
+            return response.json()
+
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        message, request_id = error_details(payload)
+        error_type = {
+            401: AuthenticationError,
+            403: ForbiddenError,
+            404: NotFoundError,
+            422: ValidationError,
+            429: RateLimitError,
+        }.get(response.status_code, AllowancesAPIError)
+        raise error_type(
+            message,
+            status_code=response.status_code,
+            request_id=request_id,
+            response=response,
+        )
+
+    def get(self, path: str, *, params: Optional[Mapping[str, Any]] = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> "AllowancesClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+

allowances_api/exceptions.py

@@ -0,0 +1,60 @@
+"""Exceptions raised by the Allowances API client."""
+
+from typing import Any, Mapping, Optional
+
+
+class AllowancesAPIError(Exception):
+    """An error response returned by the Allowances API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        request_id: Optional[str] = None,
+        response: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.response = response
+
+
+class AuthenticationError(AllowancesAPIError):
+    """The API key is missing or invalid."""
+
+
+class ForbiddenError(AllowancesAPIError):
+    """The current plan cannot access the requested resource."""
+
+
+class NotFoundError(AllowancesAPIError):
+    """The requested data was not found."""
+
+
+class ValidationError(AllowancesAPIError):
+    """One or more request parameters are invalid."""
+
+
+class RateLimitError(AllowancesAPIError):
+    """The account's request limit was exceeded."""
+
+
+class TransportError(AllowancesAPIError):
+    """The request could not reach the API."""
+
+
+def error_details(payload: Any) -> tuple[str, Optional[str]]:
+    """Extract the API's message and request ID from supported error envelopes."""
+    if not isinstance(payload, Mapping):
+        return "Allowances API request failed", None
+
+    detail = payload.get("detail", payload)
+    if isinstance(detail, Mapping):
+        return str(detail.get("message") or detail.get("detail") or detail), detail.get("request_id")
+    if isinstance(detail, list):
+        messages = [str(item.get("msg", item)) if isinstance(item, Mapping) else str(item) for item in detail]
+        return "; ".join(messages), None
+    return str(detail), None
+

allowances_api/py.typed

@@ -0,0 +1 @@
+

allowances_api/resources.py

@@ -0,0 +1,153 @@
+"""Resource clients mirroring the public v1 API routes."""
+
+from datetime import date
+from typing import TYPE_CHECKING, Any, Iterable, Optional, Union
+from urllib.parse import quote
+
+from ._utils import query_params
+
+if TYPE_CHECKING:
+    from .client import AllowancesClient
+
+DateLike = Union[str, date]
+
+
+def segment(value: Any) -> str:
+    return quote(str(value), safe="")
+
+
+class Resource:
+    def __init__(self, client: "AllowancesClient") -> None:
+        self._client = client
+
+    def _get(self, path: str, **params: Any) -> Any:
+        # Friendly Python names for API parameters whose wire names are terse or singular.
+        if "types" in params:
+            params["type"] = params.pop("types")
+        if "query" in params:
+            params["q"] = params.pop("query")
+        return self._client.get(path, params=query_params(**params))
+
+
+class DSSRResource(Resource):
+    def allowances(
+        self, country: str, *, date: Optional[DateLike] = None,
+        types: Optional[Iterable[str]] = None, verification_url: bool = False,
+    ) -> Any:
+        return self._get(f"/dssr/allowances/{segment(country)}", date=date, type=types,
+                         verification_url=verification_url)
+
+    def allowances_by_location(self, country: str, location: str, **params: Any) -> Any:
+        return self._get(f"/dssr/allowances/{segment(country)}/location/{segment(location)}", **params)
+
+    def allowances_by_postcode(self, country: str, postcode: Union[str, int], **params: Any) -> Any:
+        return self._get(f"/dssr/allowances/{segment(country)}/postcode/{segment(postcode)}", **params)
+
+    def perdiem(self, country: str, **params: Any) -> Any:
+        return self._get(f"/dssr/perdiem/{segment(country)}", **params)
+
+    def perdiem_by_location(self, country: str, location: str, **params: Any) -> Any:
+        return self._get(f"/dssr/perdiem/{segment(country)}/location/{segment(location)}", **params)
+
+    def perdiem_by_postcode(self, country: str, postcode: Union[str, int], **params: Any) -> Any:
+        return self._get(f"/dssr/perdiem/{segment(country)}/postcode/{segment(postcode)}", **params)
+
+    def search_perdiem(self, query: str, *, date: Optional[DateLike] = None) -> Any:
+        return self._get("/dssr/perdiem/search", q=query, date=date)
+
+    def locations(self, *, query: Optional[str] = None, offset: int = 0, limit: int = 10) -> Any:
+        return self._get("/dssr/locations", q=query, offset=offset, limit=limit)
+
+    def countries(self, *, query: Optional[str] = None, offset: int = 0, limit: int = 20) -> Any:
+        return self._get("/dssr/countries", q=query, offset=offset, limit=limit)
+
+    def country(self, country: str) -> Any:
+        return self._get(f"/dssr/country/{segment(country)}")
+
+    def country_locations(self, country: str) -> Any:
+        return self._get(f"/dssr/country/{segment(country)}/locations")
+
+    def calculate_cola(
+        self, postcode: Union[str, int], *, family_size: int, base_salary: int,
+        date: Optional[DateLike] = None,
+    ) -> Any:
+        return self._get(f"/dssr/cola-calculator/postcode/{segment(postcode)}",
+                         family_size=family_size, base_salary=base_salary, date=date)
+
+
+class DTMOResource(Resource):
+    def perdiem_conus(
+        self, state: str, *, date: Optional[DateLike] = None, year: Optional[int] = None,
+        query: Optional[str] = None, verification_url: bool = False,
+        offset: int = 0, limit: int = 50,
+    ) -> Any:
+        return self._get(f"/dtmo/perdiem/conus/{segment(state)}", date=date, year=year, q=query,
+                         verification_url=verification_url, offset=offset, limit=limit)
+
+    def perdiem_oconus(self, country: str, **params: Any) -> Any:
+        return self._get(f"/dtmo/perdiem/oconus/{segment(country)}", **params)
+
+    def search_perdiem(
+        self, query: str, *, date: Optional[DateLike] = None, year: Optional[int] = None,
+        verification_url: bool = False,
+    ) -> Any:
+        return self._get("/dtmo/perdiem/search", q=query, date=date, year=year,
+                         verification_url=verification_url)
+
+    def locations_conus(self, state: str) -> Any:
+        return self._get(f"/dtmo/locations/conus/{segment(state)}")
+
+    def locations_oconus(self, country: str, *, location: Optional[str] = None) -> Any:
+        return self._get(f"/dtmo/locations/oconus/{segment(country)}", location=location)
+
+
+class GSAResource(Resource):
+    def perdiem_by_destination(self, destination_id: int, **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/destination/{destination_id}", **params)
+
+    def perdiem_by_state(self, state: str, **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/state/{segment(state)}", **params)
+
+    def perdiem_by_state_year(self, state: str, year: int, **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/state/{segment(state)}/year/{year}", **params)
+
+    def perdiem_by_zipcode(self, zipcode: Union[str, int], **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/zipcode/{segment(zipcode)}", **params)
+
+    def perdiem_by_zipcode_year(self, zipcode: Union[str, int], year: int, **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/zipcode/{segment(zipcode)}/year/{year}", **params)
+
+    def zipcodes(self, state: str, *, offset: int = 0, limit: int = 20) -> Any:
+        return self._get(f"/gsa/zipcodes/{segment(state)}", offset=offset, limit=limit)
+
+    def zipcode(self, zipcode: Union[str, int]) -> Any:
+        return self._get(f"/gsa/zipcode/{segment(zipcode)}")
+
+    def counties(
+        self, *, query: Optional[str] = None, state: Optional[str] = None,
+        offset: int = 0, limit: int = 20,
+    ) -> Any:
+        return self._get("/gsa/counties", q=query, state=state, offset=offset, limit=limit)
+
+    def destination(self, destination_id: int) -> Any:
+        return self._get(f"/gsa/destination/{destination_id}")
+
+    def destinations(self, *, offset: int = 0, limit: int = 100) -> Any:
+        return self._get("/gsa/destinations", offset=offset, limit=limit)
+
+    def states(self) -> Any:
+        return self._get("/gsa/states")
+
+    def mileage(
+        self, *, date: Optional[DateLike] = None, mileage_type: Optional[str] = None,
+        verification_url: bool = False,
+    ) -> Any:
+        return self._get("/gsa/mileage", date=date, type=mileage_type,
+                         verification_url=verification_url)
+
+    def vehicle_rates(
+        self, rate_type: str, sin: str, *, year: Optional[int] = None,
+        verification_url: bool = False,
+    ) -> Any:
+        return self._get(f"/gsa/vehicle-rates/{segment(rate_type)}/{segment(sin)}", year=year,
+                         verification_url=verification_url)

allowances_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: allowances-api
+Version: 0.1.0
+Summary: Official Python SDK for the Allowances API
+Project-URL: Homepage, https://www.allowancesapi.com
+Project-URL: Documentation, https://www.allowancesapi.com/docs
+Project-URL: Repository, https://github.com/allowances-api/allowances-api-python
+Project-URL: Issues, https://github.com/allowances-api/allowances-api-python/issues
+Author-email: Allowances API <contact@allowancesapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: allowances,dssr,dtmo,gsa,per-diem,travel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Allowances API Python SDK
+
+The official Python client for [Allowances API](https://www.allowancesapi.com), 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
+
+```bash
+pip install allowances-api
+```
+
+Python 3.9 or newer is required.
+
+## Authentication
+
+Create an API key at [allowancesapi.com](https://www.allowancesapi.com), then provide it directly:
+
+```python
+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.
+
+```bash
+export ALLOWANCES_API_KEY="ak_live_your_key"
+```
+
+```python
+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:
+
+```python
+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
+
+```python
+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
+
+```python
+# 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
+
+```python
+mileage = client.gsa.mileage(mileage_type="automobile")
+fleet = client.gsa.vehicle_rates("standard", "10B", year=2026)
+```
+
+### Browse locations
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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](https://www.allowancesapi.com/docs) for response fields, plan limits, and data-source details.
+
+## Development and publishing
+
+```bash
+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`:
+
+```bash
+twine upload dist/*
+```
+
+## License
+
+MIT
+

allowances_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+allowances_api/__init__.py,sha256=_U5ICCLtZINjCh7fmxIlYYtmJPn3W9z6y1-8OpEufHA,482
+allowances_api/_utils.py,sha256=nEspXOgbEhU8m_pqRqll58qCmRhtbuhpaIGJu1Snkh8,717
+allowances_api/client.py,sha256=4Hp2kEL31BY3FiGBNUy_yIjqdzuP3tvyVo_GstwoWkc,2936
+allowances_api/exceptions.py,sha256=w7PF5iillU6aAE7qBkjuWOqQJhOSlBOdPYgSpFoN4fg,1781
+allowances_api/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+allowances_api/resources.py,sha256=tMPI4qLL-DvdZNEYK5EDAhtVbjpM-HZRtbBUzZEY6rw,6730
+allowances_api-0.1.0.dist-info/METADATA,sha256=XGfTCoVhzKjPQMI6cTMbT0tIZkVK1b0kGe53AvXUjas,6943
+allowances_api-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+allowances_api-0.1.0.dist-info/licenses/LICENSE,sha256=Yk7ewbhJM5FCcIL7KaoBH5Oi2uz5LRgGUTaVlhYSONU,1072
+allowances_api-0.1.0.dist-info/RECORD,,

allowances_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

allowances_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Allowances API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+