GSA Per Diem

locations: list of {"city": "...", "state": "XX"} dicts (optionally
with "county"), max 25 entries. Returns rates sorted by max daily
total (highest first). Ambiguous or unresolved cities are listed with
their status and candidate rate areas instead of a rate.

Useful for travel IGCE development when comparing destination costs.

Calculates lodging + M&IE for the specified number of nights.
First and last travel days use 75% M&IE per 41 CFR 301-11.20.

travel_month: 3-letter abbreviation (Jan, Feb, ..., Dec). Every night is
priced at that month's rate; for a trip that crosses into another month
or fiscal year, add only each month's lodging_total at the applicable
fiscal year rate. Calculate M&IE once across the actual trip days,
using 75% only on the actual departure and return days. Do not add
separate monthly mie_total or grand_total values: each estimate
assumes a new trip.
If omitted, uses the max monthly lodging rate (conservative estimate
for IGCE).
fiscal_year: if omitted, the FY of the next occurrence of travel_month
(or the current FY when no month is given). Pass it for a trip that
already happened.
county: optional; selects the rate area when the city spans more than
one (see lookup_city_perdiem).

No estimate is produced when the city is ambiguous or unresolved; the
candidate rate areas are returned instead.

Does NOT include airfare or ground transportation.

Formula:
- Lodging = nightly_rate * num_nights
- M&IE = full_day_rate * (travel_days - 2) + first/last_day_rate * 2
- Travel days = num_nights + 1

num_nights bounded 1-365.

Returns lodging rates (monthly breakdown for seasonal locations) and
M&IE (meals and incidental expenses) for the specified fiscal year.

state: 2-letter USPS code (e.g., 'DC', 'VA', 'MD', 'CA').
fiscal_year: defaults to current FY. FY runs Oct 1 - Sep 30, so
FY2026 = 2025-10-01 through 2026-09-30.
county: optional county or independent city (e.g., 'Fairfax',
'Hampden', 'Richmond city'). When given for a bundled fiscal year the
rate is determined from GSA's county definitions without an API call.

Without county, the GSA Per Diem API resolves the city name to rate
areas. The result's status is:
- resolved: one rate applies (exact name, composite name such as
  'Boston / Cambridge', GSA's own city-to-county resolution, or a
  Census county tie-break among GSA's candidates)
- ambiguous: GSA lists several rate areas for the city; candidates are
  returned and no single rate is chosen
- unresolved: GSA did not recognize the city; no rate is asserted

CONUS only: AK, HI, and territories return a pointer to DoD/State rates.

Returns every city/county with rates above the standard rate in that
state, plus the state's standard rate. Seasonal areas include their
lodging rate for each month (lodging_by_month). Useful for comparing rates
across cities within a state or for building a travel IGCE with
multiple destinations. Bundled fiscal years are answered from GSA's
published files with no API call.

CONUS only: AK, HI, and territories return a pointer to DoD/State rates
instead of an empty list that would falsely imply the standard CONUS
rate applies there.