To estimate CONUS travel costs for a contractor proposal, describe each itinerary, supply your lodging assumptions and deductible meals, and send the trip to the Allowances API GSA trip calculator. It returns daily lodging and meals and incidental expenses (M&IE), effective dates, and trip totals. A small Python client can then multiply those totals by traveler count and save the evidence with the estimate.
This walkthrough follows a runnable Python example for Washington and San Diego. It shows how the request becomes a reviewable proposal cost input, including what happens when a lodging assumption is missing.
Run the GSA contractor proposal example on GitHub, or follow the calculation below before trying it.
The figures below are illustrative snapshots captured from the local development API on November 3, 2026, not live quotes or guaranteed future rates. The calculator supplies a GSA-based planning model; the solicitation and approved estimating policy determine whether and how that model applies.
Define the itineraries and estimating assumptions
Start with two scenarios. Everyone within a scenario shares the same itinerary, room-cost assumption, and meal treatment. Separate travelers into different scenarios when those inputs differ.
| Scenario | Itinerary | Travelers | Assumed room cost |
|---|---|---|---|
| Washington site visit | November 9–12, 2026: Washington | 3 | $200 per night |
| Washington and San Diego review | November 16–18: Washington; November 18–20: San Diego | 2 | Washington: $200 per night; San Diego: $180 per night |
Scroll horizontally to see all columns
For the site visit, the estimator has determined that lunch on November 10 requires a deduction. That decision is an input: the calculator does not decide whether a furnished meal is deductible. GSA's official M&IE breakdown guidance explains meal components and exceptions, including complimentary hotel meals.
The example excludes airfare, lodging taxes, ground transport, other costs, and escalation. The supplied room costs are proposal assumptions, although the API field calls them lodging actuals.
Send one trip to the calculator
The endpoint is POST /v1/gsa/calc/perdiem/trip, authenticated with an X-API-Key header. Save this request as washington-trip.json:
{
"stops": [
{
"location": {"destination_id": 75},
"arrival_date": "2026-11-09",
"departure_date": "2026-11-12",
"lodging_cost_per_night": 200
}
],
"deductible_meals": [
{"date": "2026-11-10", "meals": ["lunch"]}
],
"verification_url": true
}
Make your API key available as ALLOWANCES_API_KEY in your terminal environment, then run:
curl --fail-with-body \
'https://api.allowancesapi.com/v1/gsa/calc/perdiem/trip' \
--header "X-API-Key: ${ALLOWANCES_API_KEY}" \
--header 'Content-Type: application/json' \
--data-binary @washington-trip.json
Destination 75 is Washington and 34 is San Diego in the destination catalog verified for this example. Find or check IDs through GET /v1/gsa/destinations, reviewing the full rate-area definition. The calculator accepts destination IDs or supported ZIP codes, rather than city strings. An ambiguous ZIP requires an explicit choice of destination.
Choose dates your subscription and the published data support; see pricing and the API reference. The sample's fixed November 2026 dates will eventually become historical. The script never moves the dates automatically or forecasts an unpublished rate.
Read the daily calculation before using the total
The recorded Washington response used a $203 nightly lodging cap and a $92 full-day M&IE rate. The assumed $200 room cost was below that cap. The response identified the per diem effective date as October 1, 2026, and the M&IE breakdown effective date as June 23, 2026.
| Day | Lodging cap | Assumed room cost | Lodging payable | M&IE calculation | M&IE payable |
|---|---|---|---|---|---|
| November 9: first travel day | $203.00 | $200.00 | $200.00 | $92 × 0.75 | $69.00 |
| November 10: lunch deduction | $203.00 | $200.00 | $200.00 | $92 − $26 | $66.00 |
| November 11: full day | $203.00 | $200.00 | $200.00 | $92 | $92.00 |
| November 12: return day | No night | — | — | $92 × 0.75 | $69.00 |
| Total | $600.00 | $296.00 |
Scroll horizontally to see all columns
Four travel days produce three lodging nights. The recorded per-traveler total was $896.00, making the three-person planning amount $2,688.00.
The API handles date-specific rate selection, first/last-day proration, meal deduction math, and lodging caps. The client uses the returned amounts rather than implementing those rules again. When room costs exceed a cap, the calculator reports the overage separately from payable lodging.
Handle the multi-stop trip and traveler groups
For the second scenario, the first stop departs Washington on November 18 and the next stop arrives in San Diego on November 18. These are contiguous stops: the arriving stop owns the shared date, so San Diego supplies that day's locality. A stop represents the temporary-duty locality, not simply the hotel's address.
The recorded second response returned four lodging nights, with $760.00 in lodging and $397.50 in M&IE per traveler. The Python client multiplied the API totals by the two-person headcount using decimal arithmetic.
| Scenario | Travelers | Lodging per traveler | M&IE per traveler | Total per traveler | Group total |
|---|---|---|---|---|---|
| Washington site visit | 3 | $600.00 | $296.00 | $896.00 | $2,688.00 |
| Washington and San Diego review | 2 | $760.00 | $397.50 | $1,157.50 | $2,315.00 |
| Total | $5,003.00 |
Scroll horizontally to see all columns
The sample proposal total comprised $3,320.00 in group lodging and $1,683.00 in group M&IE. No lodging overage was returned for these assumptions. These totals exclude the other travel costs listed above.
Run the Python example
The standalone example requires Python 3.10 or later, an Allowances API key, and network access. It uses Python's standard library, so no package installation or application database is needed.
Download the Allowances API examples repository, or clone it:
git clone https://github.com/allowancesapi/allowances-api-examples.git
cd allowances-api-examples/gsa-contractor-proposal
Get an API key, then set ALLOWANCES_API_KEY in your environment using the example's setup instructions and run:
python3 proposal_estimate.py sample-proposal.json --output estimate/
One request is sent per scenario, rather than per traveler or day. Headcounts and proposal labels stay outside the API request body. Use a new output directory for each revision; the script refuses to overwrite an existing estimate.
The example produces four files:
| File | What the reviewer can check |
|---|---|
summary.csv |
Per-traveler and group amounts, travel dates, day/night counts, and completeness. |
daily.csv |
Locality, source, fiscal year, effective dates, meal components, and lodging figures for each day. |
rate-evidence.json |
Requests, complete responses, timestamps, source links, request IDs, calculation version, and source fingerprint. |
assumptions.md |
Assumed room costs, caller-submitted meal deductions, API notes, exclusions, and the proposal total when complete. |
Scroll horizontally to see all columns
Keep those files with your estimating workpapers. Saved responses preserve the values used even if later runs change; the source fingerprint identifies source values but does not recreate an old dataset. Keep credentials out of the saved evidence.
You can inspect the recorded summary and full rate evidence without an API key. These files are the illustrative local snapshots used in this walkthrough.
Leave unknown lodging costs visibly incomplete
Try the variant without room-cost assumptions:
python3 proposal_estimate.py sample-missing-lodging.json --output estimate-missing/
The calculator can return lodging caps and M&IE while lodging payable and the combined total remain null. The example preserves those unknown values as blank CSV amounts, labels the proposal incomplete, and produces no complete proposal total. A nightly cap is not silently substituted for an assumed room cost.
The CLI returns exit code 0 for complete output, 2 for valid but incomplete output, and 1 for a failure. If a scenario fails, available evidence is retained and no final estimate is presented as successful. Check authentication, access, quota, or structured locality errors before rerunning into a new output directory.
Use the result as a documented planning input
Review the source, resolved locality, dates, meal decisions, room assumptions, and excluded costs before incorporating the result into a proposal. Rate retrieval and calculator output do not establish contractor cost allowability or approval. Allowances API is an independent service, not affiliated with the U.S. government.
Start with a single itinerary, compare the daily breakdown with the returned evidence, then add scenarios with shared assumptions. For related workflows, see automating government allowance lookups and automating overseas allowances for contractor proposals. The overseas guide uses different sources; this runnable example covers GSA CONUS travel.