# Travel Budget Itinerary Builder (`rustic_soybean/travel-budget-itinerary-builder`) Actor

Plan a trip around a destination or budget. Compare current flights and stays, discover local places, read traveler reviews, and see linked meal and transport prices. Prices found on opened pages include source links; estimates and unverified results are labeled.

- **URL**: https://apify.com/rustic_soybean/travel-budget-itinerary-builder.md
- **Developed by:** [Chris Johnson](https://apify.com/rustic_soybean) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Budget-First Travel Planner

Find trip options around a destination or a budget. Compare current flight and lodging listings, discover local places, read a small sample of traveler reviews, and see source-linked meal and ground-transport price evidence. The Actor plans; it does not book travel.

### Price

The Actor's fee is **$0.05 per completed itinerary plan**. Apify platform usage and any separately billed source Actor usage may add to the total; check the run's source costs and Apify Store pricing before starting.

### Choose a planning mode

- **Cheapest destinations:** Enter a departure city to see up to five current flight deals. Add a country to filter them. Local suggestions and cost research use the cheapest matching destination.
- **Specific destination:** Enter a destination and travel dates. Add airport or metro codes if you want airfare, and choose which costs to include.
- **Budget:** Enter a total budget. Add a destination and dates to compare that place, or leave the destination blank to start with current flight deals from your departure city.

Choose **Cheapest**, **Best value**, or **High-end**. Cheapest sorts by known costs, then airfare when a full subtotal is unavailable. Best value considers lodging ratings and known costs. High-end favors higher-rated stays. Ratings are user-submitted summaries, not professional reviews.

### What the Actor checks

- Flight offers and current destination deals.
- Lodging listings and ratings when dates are available.
- Local attractions, restaurants, and a small sample of Google Maps reviews, with reviewer identity omitted.
- When meals or ground transport are selected, local fare and meal searches, traveler reports, and up to four opened source pages. Clear amounts found on those pages are returned with their text, link, currency when known, and check time. If a page cannot be opened or no clear amount is found, the search preview is kept and labeled.
- Draft day plans that group places across the trip. They are suggestions, not verified routes or travel times.

### How to read costs

The **known-cost subtotal is not the final trip price**. It includes returned airfare and lodging prices, plus meal or ground-transport allowances only if you enter them. It excludes unconfirmed local cost evidence, baggage, taxes and fees, activity tickets, and other missing costs. A price quoted on an opened page can still have conditions or be out of date, so it is shown separately instead of being silently added to the subtotal. Prices in different currencies are not converted or combined.

Traveler reports and reviews are anecdotal, not official prices. A date shown by Google may not be the date the linked page was last updated. The page check time shows when the Actor opened it.

### Keep costs predictable

- The default pay-per-event source cap is $0.15. Within it, up to $0.02 is reserved for local searches and $0.01 for opening source pages; local places and reviews use a separate shared allowance. Lower caps can cause some sources to be skipped. Check `SUMMARY` for the actual source status and limits.
- The flight-deal source is billed by its author as compute usage and is outside that pay-per-event cap. Its result count is limited.
- Flexible-date price trends are off by default because they use a browser-enabled source run.
- Search and source Actor prices can change. Check their linked Apify Store pages before increasing use or scheduling runs.

### Example inputs

#### Plan a specific trip

```json
{
  "mode": "specific_destination",
  "origin": "PHL",
  "destination": "Paris",
  "destinationCode": "PAR",
  "departureDate": "2027-04-10",
  "returnDate": "2027-04-15",
  "adults": 2,
  "travelStyle": "best_value",
  "budget": 2500,
  "currency": "USD",
  "include": ["airfare", "lodging", "meals", "ground_transport", "local_places"],
  "mealBudgetPerPersonPerDay": 60,
  "country": "France"
}
```

#### Find destinations with cheap flights

```json
{
  "mode": "cheapest_destinations",
  "departureCity": "New York",
  "country": "Italy",
  "travelYear": 2027,
  "travelStyle": "cheapest",
  "currency": "USD",
  "include": ["airfare", "lodging", "meals", "ground_transport", "local_places"],
  "tripDays": 5
}
```

#### Search destinations within a budget

```json
{
  "mode": "budget",
  "departureCity": "New York",
  "country": "Italy",
  "travelYear": 2027,
  "budget": 1800,
  "travelStyle": "cheapest",
  "currency": "USD",
  "include": ["airfare", "lodging", "meals", "ground_transport", "local_places"],
  "tripDays": 5
}
```

For fixed-destination airfare, use airport or metro codes for both ends (for example, `PHL` and `PAR`). Enter the city name separately for lodging and local searches. For broad deal searches, the source may omit the year; enter `travelYear` to check lodging dates without guessing.

### Results

The dataset can contain itinerary options, flight deals and offers, lodging listings, local places, reviews, draft day plans, and `local_cost_evidence` rows. The `SUMMARY` key-value record lists source status, result counts, destination coverage, price notes, and spend caps. Inspect the evidence status before relying on an amount.

### Sources

- [Google Flights Deals](https://apify.com/rainminer/google-flights-deals-scraper)
- [Google Travel](https://apify.com/nextgensda/google-travel)
- [Google Maps Places](https://apify.com/agenttoolworks/google-maps-places-scraper)
- [Google Maps Reviews](https://apify.com/compass/google-maps-reviews-scraper)
- [Google Search Scraper](https://apify.com/apify/google-search-scraper)
- [Web Fetch](https://apify.com/apify/web-fetch)

Each source Actor is maintained separately. Its availability, output, and price can change.

# Actor input Schema

## `mode` (type: `string`):

Choose destinations with the lowest current airfare, plan a trip to a named destination, or keep a trip within your total budget.

## `departureCity` (type: `string`):

For the cheapest-destination search, enter a major city supported by Google Flights Deals, such as New York, Los Angeles, London, or Tokyo.

## `origin` (type: `string`):

Use an airport or metro code such as PHL, JFK, NYC, or LON. Required when airfare is included in a specific-destination or budget search.

## `destination` (type: `string`):

Enter the destination city in plain English, such as Paris. Used for hotel and local-place searches.

## `destinationCode` (type: `string`):

Required only when airfare is included for a fixed destination. Use a code such as PAR, CDG, or LHR.

## `country` (type: `string`):

Optional country filter for broad flight-deal searches, for example Italy. For a named destination, enter its country here to localize local-cost web searches; if blank or unrecognized, those searches use US Google results.

## `travelYear` (type: `integer`):

Optional for cheapest-destination and budget searches without fixed dates. The deal source often omits the year; enter a year to match its month/day and search lodging for those dates without guessing.

## `departureDate` (type: `string`):

Required for a specific destination or a budget search with a destination. Use YYYY-MM-DD. Flexible deal searches use current discounted dates instead.

## `returnDate` (type: `string`):

Required for a specific destination or a budget search with a destination. Use YYYY-MM-DD and make it later than the departure date.

## `adults` (type: `integer`):

Number of adults traveling. Enter a value from 1 to 8.

## `children` (type: `integer`):

Number of children traveling. Enter 0 if no children are traveling.

## `travelStyle` (type: `string`):

Cheapest sorts by known trip costs or airfare when a full subtotal is unavailable. Best value balances observed lodging ratings and known costs. High-end puts highly rated stays first. Ratings are not professional reviews.

## `budget` (type: `number`):

Total budget for everyone, in the selected currency. The Actor compares it with known costs; missing prices and fees may make the final trip cost higher.

## `currency` (type: `string`):

Three-letter currency code, such as USD, CAD, GBP, or EUR.

## `include` (type: `array`):

Turn off categories you want to leave out of the comparison. The Actor only searches categories you include.

## `mealBudgetPerPersonPerDay` (type: `number`):

Optional planning estimate in your selected currency. This is your estimate, not a live restaurant quote. Leave blank to keep meals out of the subtotal; the Actor will still search for linked meal-price evidence when Meals is selected.

## `groundTransportBudget` (type: `number`):

Optional total estimate in your selected currency. This is your estimate, not a live transit or rental-car quote.

## `tripDays` (type: `integer`):

Used for meal estimates and day-by-day place suggestions. Leave blank to calculate from fixed dates, or use five days for flexible deal searches.

## `interests` (type: `array`):

Optional search terms such as museums, hiking, live music, food markets, or beaches. The Actor checks up to two interests (one when restaurant search is included) to keep costs low.

## `maxOptions` (type: `integer`):

Maximum number of itinerary options to include in the results.

## `maxSourceSpendUsd` (type: `number`):

Maximum combined allowance for capped pay-per-event sources, divided among flights or lodging, local places, reviews, local cost searches, and opening up to four local source pages. Default $0.15. The separate flight-deal source is billed by its author as compute usage, so this cap does not cover it; its result count is limited.

## `enablePriceTrends` (type: `boolean`):

Off by default to save money. When enabled for a specific route, requests a 30-day Google Flights price graph and starts a browser in the source Actor.

## Actor input object example

```json
{
  "mode": "specific_destination",
  "adults": 1,
  "children": 0,
  "travelStyle": "best_value",
  "currency": "USD",
  "include": [
    "airfare",
    "lodging",
    "meals",
    "local_places"
  ],
  "interests": [],
  "maxOptions": 5,
  "maxSourceSpendUsd": 0.15,
  "enablePriceTrends": false
}
```

# Actor output Schema

## `results` (type: `string`):

Records for trip options, draft daily suggestions, lodging, local places, traveler reviews, and local cost evidence. Amounts quoted from opened pages are separated from unverified search previews and traveler reports.

## `summary` (type: `string`):

Search coverage, source status, ranking method, price trends, budget caveats, and per-run spend caps.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("rustic_soybean/travel-budget-itinerary-builder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("rustic_soybean/travel-budget-itinerary-builder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call rustic_soybean/travel-budget-itinerary-builder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rustic_soybean/travel-budget-itinerary-builder"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/zpnULCMBgEAAhq1an/builds/Efw6zm3RNIZJRPib7/openapi.json