Almosafer APIalmosafer.com ↗
Search Almosafer flights, get fare calendars, and look up airport/airline info via 3 structured endpoints returning real-time pricing and itinerary data.
What is the Almosafer API?
The Almosafer API provides 3 endpoints for querying flight data from almosafer.com, covering one-way and round-trip itinerary search, date-range fare calendars, and IATA code lookups. The search_flights endpoint returns per-itinerary fields including price, duration, stop count, baggage allowance, and seat availability across Economy, Business, and First cabin classes in any supported currency.
curl -X GET 'https://api.parse.bot/scraper/775b2738-2d03-4e34-a269-8c51b572e0a2/search_flights?cabin=Economy&adults=1&origin=RUH&infants=0&sort_by=price&airlines=SV&children=0¤cy=USD&max_price=5000&max_stops=1&min_price=0&destination=JED&return_date=2026-07-31&nonstop_only=false&departure_date=2026-07-24&refundable_only=false' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace almosafer-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Almosafer Flight Search — find cheap flights, compare fares across dates, look up airports."""
from parse_apis.almosafer_flight_search_api import Almosafer, Cabin, Sort, RouteNotFound
client = Almosafer()
# Search nonstop flights from Riyadh to Jeddah, sorted by price
for flight in client.flights.search(
origin="RUH", destination="JED", departure_date="2026-07-01",
cabin=Cabin.ECONOMY, sort_by=Sort.PRICE, nonstop_only="true", limit=5
):
print(flight.airline, flight.duration_minutes, flight.price.total, flight.price.currency)
# Fare calendar: cheapest price per date over a week
cheapest_fare = client.fares.calendar(
origin="RUH", destination="DXB",
departure_from="2026-07-01", departure_to="2026-07-07",
limit=3
).first()
if cheapest_fare:
print(cheapest_fare.departure_date, cheapest_fare.price, cheapest_fare.airline)
# Look up airport details by IATA codes
for airport in client.airports.lookup(codes="RUH,JED,DXB", limit=5):
print(airport.code, airport.name, airport.city, airport.country)
# Typed error handling for a route that may not exist
try:
for flight in client.flights.search(
origin="RUH", destination="XYZ", departure_date="2026-07-01", limit=1
):
print(flight.id)
except RouteNotFound as exc:
print(f"Route not found: {exc.origin} -> {exc.destination}")
print("exercised: flights.search / fares.calendar / airports.lookup / RouteNotFound")Search for flights between airports with optional filtering by airline, stops, price, and more. Supports one-way and round-trip searches across all cabin classes. Returns flight itineraries sorted by the specified criteria. The upstream search is asynchronous — the scraper polls until all provider results are collected.
| Param | Type | Description |
|---|---|---|
| cabin | string | Cabin class: Economy, Business, First |
| adults | integer | Number of adult passengers |
| originrequired | string | Origin airport IATA code (e.g., RUH, DXB, JFK) |
| infants | integer | Number of infant passengers (under 2) |
| sort_by | string | Sort results by: price, duration, stops |
| airlines | string | Filter by airline codes, comma-separated (e.g., SV,F3,XY) |
| children | integer | Number of child passengers (2-11 years) |
| currency | string | Price currency code (USD, SAR, EUR, etc.) |
| max_price | number | Maximum total price filter |
| max_stops | integer | Maximum number of stops (0 for nonstop) |
| min_price | number | Minimum total price filter |
| destinationrequired | string | Destination airport IATA code (e.g., JED, CAI, LHR) |
| return_date | string | Return date in YYYY-MM-DD format. Omit for one-way search |
| nonstop_only | string | Set to 'true' to show only nonstop flights |
| departure_daterequired | string | Departure date in YYYY-MM-DD format |
| refundable_only | string | Set to 'true' to show only refundable fares |
{
"type": "object",
"fields": {
"search": "object containing search parameters summary (origin, destination, departure_date, return_date, cabin, passengers, currency, trip_type)",
"flights": "array of flight objects with id, airline, flight_codes, price, duration_minutes, total_stops, baggage, seats_available, has_fare_families",
"total_results": "integer count of flights returned",
"airlines_found": "array of unique airline IATA codes in results"
}
}About the Almosafer API
Flight Search
The search_flights endpoint accepts a required origin and destination as IATA codes and a departure_date, with optional filters for cabin, airlines (comma-separated IATA codes), stops, and price range. Results are returned as an array of flight objects, each containing id, airline, flight_codes, price, duration_minutes, total_stops, baggage, seats_available, and a has_fare_flexibility flag. The sort_by parameter accepts price, duration, or stops. The airlines_found array in the response lets you see which carriers are present in the result set without scanning individual records.
Fare Calendar
The get_fares_calendar endpoint returns the cheapest one-way price for each date in a specified range between an origin and destination. The range is defined by departure_from and departure_to in YYYY-MM-DD format; ranges wider than 7 days are automatically broken into multiple requests and merged. Each entry in the fares array includes departure_date, price, airline, currency, and source. A top-level cheapest object surfaces the lowest-priced fare in the range without requiring client-side iteration.
Airport and Airline Lookup
The get_airport_info endpoint resolves one or more IATA codes — airports and airlines can be mixed in a single comma-separated codes parameter. Airport objects return code, name, city, country, and country_code. Airline objects return code and name. This is useful for displaying human-readable labels when building UIs on top of the search or calendar endpoints, which return raw IATA codes throughout.
The Almosafer API is a managed, monitored endpoint for almosafer.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when almosafer.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official almosafer.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a flexible date tool that shows the cheapest flight for each day in a month using
get_fares_calendar - Compare prices across airlines on a route by filtering
search_flightswith specificairlinescodes - Display route summaries with full airport names by resolving IATA codes via
get_airport_info - Find the shortest-duration itinerary on a route by setting
sort_by=durationinsearch_flights - Monitor seat availability and prices on specific flights using
seats_availablefrom search results - Identify which carriers serve a given route by reading the
airlines_foundfield from a flight search - Resolve a mixed list of airline and airport IATA codes to display names in a travel dashboard
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Almosafer have an official public developer API?+
What does `search_flights` return beyond the ticket price?+
duration_minutes, total_stops, flight_codes, baggage allowance details, seats_available (a count or flag), and has_fare_flexibility. The top-level response also contains airlines_found — the distinct set of airline codes that appear in the result set — and total_results for the unfiltered count.How does the fare calendar handle wide date ranges?+
departure_from/departure_to range wider than 7 days, the API automatically chunks the range into sequential 7-day windows, fetches each, and merges the results into a single fares array. The total_combinations field tells you how many distinct dates have fare data in the final merged response.Does the API return hotel or car rental data from Almosafer?+
Can I get historical fare data or price trend charts across multiple months?+
get_fares_calendar endpoint returns current lowest fares for future dates in a given range; it does not expose historical pricing or past fare trends. You can fork this API on Parse and revise it to add a historical data endpoint if that data becomes accessible through the source.