Flytoday

Tours, tickets and experiences in a destination that are on sale in the date range, with from-prices. Only activities with a price in the range are listed (many are unavailable on given dates), cheapest first. price_toman is the adult from-price; list_price_toman is the box-office price. region is the destination matched; other_regions lists alternatives to retry with region_id. Next: ft_activity(activity_id).

One activity: description, highlights, options with adult prices, and the cheapest days in the range. price_toman fields are adult prices. The range matters: an activity with no availability in it comes back with available=false, so use a wide range (the default is about two months). Slow upstream (up to a minute). Booking happens on flytoday.ir.

Cheapest bus seat price per day for the next weeks (the site's price strip), in one cheap call. Values are cached minimums per day (one row per company in the API) and can differ a little from a live search; days without a listed bus are left out. Use it to pick a day, then ft_search_buses.

CIP / VIP airport lounge service with prices for a date and passenger mix, plus paid add-ons. Only IKA and MHD sell CIP. `nationality` says which passports an offer is for (IKA lists one offer for Iranian passports and one for all others). price_per_passenger_toman is per person (tax included); total_toman is for the whole party; add-ons (wheelchair, pet, transfers) list their adult price. Nothing is held or booked. Next: the user books on flytoday.ir.

eSIM data plans for a country with data amount, validity days and price, cheapest first. Covers 200+ countries (no regional or global bundles). fare_code identifies the plan on flytoday.ir; plans cannot be bought here. coverage_countries is how many countries the plan works in.

Find the IATA codes the flight tools need, for domestic and international places. Each hit has `code`, `type` (City or Airport) and, for a city, its `airports`. Use the city code (THR, IST) in ft_search_flights and ft_flight_calendar: a city code covers all of its airports. Without a query it lists the popular Iranian and international cities.

Bus city ids (4 digits) for a city name, or the popular cities when query is empty. Use before ft_search_buses (Tehran '0001', Isfahan '0002', Shiraz '0004', Mashhad '0006').

Find the place ids the hotel and stay tools need. Which id goes where: `hotels` rows: kind 'city' (Iran) -> `city_id` for ft_search_hotels; kind 'region' (abroad, with international=true) -> `region_code` plus `country_code` for ft_search_hotels(international=true); kind 'hotel' -> `hotel_id` for ft_hotel and ft_hotel_reviews. `stay_regions` rows (Iran only, villas and apartments) -> `region_code` for ft_search_stays; they are NOT the same ids as the hotel city ids. Without a query it lists the popular hotel places (and popular stay areas, which have no region_code: search them by name).

Train station codes (`station_code`) for a city name, or the 8 most popular stations when query is empty. Use before ft_search_trains and ft_train_calendar, which need the codes (Tehran 1, Mashhad 191).

Cheapest one-adult fare per departure day around a date, in one cheap call (no search needed). Use it to pick the cheapest day, then ft_search_flights for that day. Values are cached minimums (price_toman, airline code) and can differ a little from a live search; days without a cached fare are left out and past days are dropped. `cheapest` is the lowest day.

Refund and change rules, confirmed baggage per segment and (international) entry notes of one fare. The fare_source_code is valid only while its search lives (about 15 minutes); after that run ft_search_flights again. Charter fares list cancellation penalties as text, system fares as tiers (`penalties`, % of the fare by time before the flight).

One hotel for dates: every room and meal-plan offer with whole-stay price, rooms left and cancellation terms, the room details (size, beds, features) and the hotel basics (address, stars, score, facilities, check-in time). price_toman is the whole stay for one room; per_night_toman = price / nights. Offers are cheapest first, sold-out ones (rooms_left 0) last. Use after ft_search_hotels; the user books on flytoday.ir. Rate limited like ft_search_hotels: one availability call per use.

Guest reviews of a hotel: score (1-10), text, pros, cons, trip type and nights. Mostly Persian text. Use after ft_search_hotels / ft_hotel to judge a hotel; total_reviews tells how many pages exist.

Buses between two cities on a date: company, terminals, departure, bus type, seats left, price per seat. A busy route lists over 100 buses (the raw reply is 1.5 MB): narrow with facility, sort or limit. price_toman is per seat. Rows carry `fare_source_code`; `search_id` is at the top. The site's seat map is not offered (it belongs to the booking flow). Searches are rate limited: do not repeat them in a loop.

Search flights for a date: every flight with times, airline (airline_fa: Persian name), seats left, price and fare_source_code. price_toman is one adult's fare (taxes included), total_toman the whole party. Round trip (return_date): `flights` are outbound options (total_toman = cheapest round trip with that outbound), `return_flights` the returns for the cheapest outbound (`return_for` is its key; pass another key as outbound_key + search_id for its returns). Filters apply to the outbound leg. Rate limited: page with search_id, never search again. Next: ft_flight_details(fare_source_code); ft_flight_calendar finds the cheapest day first.

Priced hotels of a city (Iran) or region (abroad) for dates, one row per hotel with its cheapest room offer. Give city_id for Iran, or region_code + country_code with international=true. price_toman is the whole stay for one room (per_night_toman = price / nights); image is the cover photo. Next: ft_hotel(hotel_id) or ft_hotel_reviews. Rows with is_stay=true are apartments or villas: open them with ft_stay(property_id). rooms_left is given only when the site counts rooms. Captcha-limited hard per IP: search once, then filter and page; never loop.

Villas, apartments and other private stays in Iran for dates, cheapest first. Give both dates (strongly advised: only properties free on the dates are listed and total_toman is filled) or none (base prices). price_per_night_toman and total_toman are Toman (the stay API is not in Rial like hotels). property_id feeds ft_stay (calendar, details, reviews). Prices change a lot by date.

Trains between two stations on a date: one row per train class (wagon) with price per adult and seats left. price_toman is per adult. Sales cover only about the next 16 days (no_result means outside it). Rows carry `fare_source_code` and `wagon_id`: pass them to ft_train_stops for stops and amenities. Other days: ft_train_calendar. Searches are rate limited by the site: do not repeat them in a loop.

One villa / apartment: details (capacity, rooms, facilities, rules, host), the per-night price calendar with blocked days, and the review summary with the latest reviews. Calendar prices are Toman per night for that date (the base price in the details is only a reference). A day is available=false when the host blocked it or it is already reserved. The user books on flytoday.ir.

Cheapest train price per day for the next ~16 days, with sold-out days flagged. Use to pick a day; then ft_search_trains for that date.

Stops of one train with arrival and departure times, plus (with wagon_id) the class amenities and extra meals. Needs ids from a recent ft_search_trains result; they expire with the search.

Visa services of Flytoday: the country list with from-prices, or one country's prices, documents and process. Without country: every country with visa type, from_price (in price_currency, often USD or EUR, not Toman) and processing time. With country: price per visa type (foreign currency and Toman at Flytoday's rate), validity, processing time and documents. Schengen is one entry, 'schengen'.