آسمان‌جو's public API

• No key120 requests per minuteIt is counted by internet address network, not by browser.
• With this site's user session300 requests per minuteFor the pages the site itself reads behind your account.
• With an API keyA separate quota for each keyA key is obtained through the contact page and its quota is set there; the request header is X-API-Key.

Every response carries the three X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset ; when the quota runs out the response is 429 and Retry-After It tells you how many seconds to wait. The window is one minute and is counted afresh from the start of each minute.

• Every address under /api/ also answers under the /api/v1/ prefix; it is the same implementation, so the two never drift apart.
• Removing an address, renaming a parameter, or changing its default value are all locked down in one test file; changing them has to be deliberate and reviewable.
• The answer from heavy endpoints is kept for a while and carries an ETag header; if you send If-None-Match, you get a 304 and your previous copy is still valid.
• A cross-origin request from the browser is accepted only from asemanjoo.ir itself; for any other use, read it from the server side.

• “Unknown” means we do not know, and in the JSON answer it comes back as null — not as zero. A speed of zero and an altitude of zero, where the transmitter said nothing, are “unknown” too, not “zero”.
• The origin and destination of every flight has a provenance rank: 0 means none, 10 means the adsbdb callsign table, 20 means a claim whose source was not recorded, 30 means a flight schedule and 40 means our own observation on the ground. Rank 10 is the weakest: one callsign flies several routes in a single day and that table holds one route per callsign.
• The point-by-point track of flights is kept for 30 days and the flight row itself for a year; the daily roll-ups are never deleted. Which means «there was no flight» and «we no longer keep it» are two different things.
• Our coverage is the coverage of volunteer receivers, not the coverage of the sky. Where there is no receiver there is no flight — and that shows in the figures for airports with few receivers.
• Punctuality and scheduled times are available only for a minority of flights, so this is a sample, not a census.

• /api/flights

  Every flight seen inside the requested box at this moment. Rows are arrays rather than objects so they stay small; the field order is the one the site's own map reads.

  south, north, west, east, since, limit

• /api/stats/live

  The number of flights being tracked right now — one number, for when that is all you want.

• /api/stats/world

  A picture of the world at this moment: the busiest origins, destinations, airlines and types among the flights in the air.

• /api/nearest

  The flights nearest to a point, with distance in kilometres.

  lat, lon, radius_km, limit, ground

• /api/overhead

  What is overhead a point — the very question “what is this aircraft above me”.

  lat, lon, radius_km, limit

• /api/density

  Traffic density in the viewport, for drawing the density layer.

  south, north, west, east, nx, ny

• /api/top

  The flights with the most visitors on this site right now.

• /api/flights/emergency

  Flights squawking 7500, 7600 or 7700. The list is usually empty, and that is an answer too.

• /api/feed/events.rss

  The same emergency list in RSS format, for a news reader.

• /api/flight/{flight_id}

  Everything about one flight: identifier, airframe, route, recorded track and photos.

  with_trail

• /api/flight/{flight_id}/live

  Only the live part of that same flight, for when the page is open and just needs refreshing.

• /api/flight/{flight_id}/eta

  Estimated time of arrival. It is our estimate from speed and distance, not the airline's announcement.

• /api/flight/{flight_id}/geojson

  That same flight's track as GeoJSON, to drop onto any other map.

• /api/flight/{flight_id}/playback

  Replay of the flight track from our own store, point by point.

  max_points

• /api/flight/{flight_id}/history

  Past flights with the same flight number — “when this flight usually lands”.

  limit

• /api/replay

  Replay of one box of the map over a past time window.

  south, north, west, east, start, minutes, max_flights, stream

• /api/replay/export

  Export of the same replay to a GeoJSON or CSV file — for inspection and research, not video.

  south, north, west, east, start, minutes, max_flights, format

• /api/replay/airport/{iata}

  Replay of the flights that landed at or departed from this airport within a time window — selected by flight, not by geographic box, so that a flight leaving the box is not left out of the replay.

  start, minutes, max_flights

• /api/airports

  A list of airports with their Persian name, coordinates and movement count.

  fields, format

• /api/airports.csv

  The same list in CSV format, for a spreadsheet.

• /api/airports/bbox

  Airports inside a box, for the map.

  south, north, west, east, limit

• /api/airports/compare

  Two airports side by side, with the same numbers the comparison page shows.

  a, b, days

• /api/airports/disruptions

  Global and regional airport rankings based on a live index of disruption, delays and cancellations.

  hours, limit, region

• /api/airport/{iata}

  One airport: name, coordinates, runways, weather and recent stats.

• /api/airport/{iata}/full

  The four answers above — airport, board, stats and forecast — in one request.

  kind, days, board_before, board_after, stats_days, radius_km

• /api/airport/{iata}/board

  That same airport's arrivals and departures board.

  kind, before, after

• /api/airport/{iata}/stats

  Time series of the airport's traffic, day by day.

  days

• /api/airport/{iata}/delay

  An airport's delay status, right now and over the recent window — with an explicit “unknown” state when the sample is small.

  days, hours

• /api/airport/{iata}/routes

  That airport's most frequent destinations in the recent window.

  days, limit

• /api/airport/{iata}/ground

  The aircraft seen on that airport's ground at this moment.

  radius_km, limit

• /api/airport/{iata}/departures.xml

  An RSS feed of that airport's departures — the same departure board, to subscribe to in a reader without an account.

• /api/airport/{iata}/departures.json

  The same feed in JSON Feed 1.1 format, for the developer consumer.

• /api/airport/{iata}/trails

  Recent arrival and departure tracks for that same airport, condensed and ready to draw on a map (E-274).

  days

• /api/routes

  Every route with traffic, page by page with a key cursor.

  cursor, limit

• /api/route/{orig}/{dest}

  One route: flight count, landings and the airframes that fly it.

• /api/route/{orig}/{dest}/geojson

  The same track in GeoJSON format.

• /api/city/{slug}

  One city: its airports, their combined traffic and the busiest destinations.

  days

• /api/city-pair/{orig}/{dest}

  Every airport pair between two cities, gathered into one response.

  days

• /api/route/{orig}/{dest}/trails

  Recent tracks of flights on this same route, condensed and ready to draw on a map (E-46).

  days

• /api/route/{orig}/{dest}/path

  The usual path of this route, computed from the median of recent tracks — not the path of one particular flight (L-90).

  days

• /api/route/{orig}/{dest}/seasonality

  This route's seasonal pattern broken down by Persian calendar month, from the permanent stats_daily_route record (L-92).

• /api/busiest

  The busiest airports and routes of the past thirty days, in one response.

• /api/busiest/airports.csv

  The same airport ranking in CSV format.

• /api/busiest/routes.csv

  The same route ranking in CSV format.

• /api/stats/extremes

  The longest and shortest routes we have seen.

  limit, min_flights

• /api/airlines

  A list of airlines with their Persian name and flight count.

• /api/airline/{iata}

  One airline: fleet, destinations and flight count.

  days

• /api/airline/{iata}/history

  That airline's stats over a window you set yourself.

  start, end

• /api/types

  A list of aircraft types with flight count.

• /api/type/{code}

  One aircraft type: the airframes seen and the most-used routes.

  days

• /api/countries

  A list of countries with airport count and traffic.

• /api/country/{code}

  A country's flights and airports.

  days

• /api/aircraft/{reg}

  One airframe by registration: details and recent flights.

  days

• /api/aircraft/{reg}/history

  Flights by that same airframe, over a window you set yourself.

  start, end, limit

• /api/stats/daily

  Daily counts of flights, routes, airports and types. With format=csv it gives the same in CSV.

  days, format

• /api/stats/world/series

  Time series of the global flight count, one sample every five minutes — up to seven days back. An interval in which the collector took no sample stays empty; no value is interpolated in its place.

  hours

• /api/download/datasets

  A machine-readable list of the downloadable datasets: the column names, address and licence text of each.

• /api/download/{dataset}.csv

  One of the daily or yearly roll-ups in CSV format, with a header that carries the build time and the licence inside the file itself. `days` limits only the daily roll-ups; the yearly ones give the whole recorded range.

  days

• /api/search

  One search across airports, airlines, flights, routes and registrations.

  q

• /api/search/suggest

  Short suggestions while typing.

  q, limit

• /api/search/advanced

  Search with combined filters: airline, type, altitude, speed and airport.

  airline, aircraft_type, orig, dest, min_alt, max_alt, min_spd, max_spd, ground, limit

• /api/search/history

  Search a flight number, callsign or registration over a date range — up to a year back.

  q, from, to, limit

• /api/wx/hazard

  Aviation weather advisories (SIGMET/AIRMET) in the viewport.

  south, north, west, east, limit

• /api/tfr

  Active US temporary flight restrictions (TFR) in the viewport, with type (sporting/hazard/security/space/VIP/drone gathering/special) and validity window.

  south, north, west, east, limit

• /api/oceanic-tracks

  The organised oceanic tracks valid at this moment (NAT-OTS, PACOTS and AUS-OTS) together with each system's source and one status sentence.

• /api/wx/turbulence

  Turbulence layer: pilot reports (PIREP, “reported”) and the model's wind shear between two adjacent levels (“estimated”) inside the view box — two separate sub-layers.

  south, north, west, east, limit

• /api/airspace/fir

  Flight information region (FIR) boundaries inside the box.

  south, north, west, east, zoom, limit

• /api/airspace/at

  Which flight information region this point lies in.

  lat, lon

• /api/map/ground

  The navaids and runways inside the box, for the map's ground layer.

  south, north, west, east, runways, limit

• /api/sources

  Live status of the data sources: which of them answer and how large each one's share is.

  hours

• /api/punctuality

  Airports whose departure sample reaches the publication floor, with the real data window. No percentage is returned — numerator and denominator separately, so that no share reaches the reader without its sample.

• /api/punctuality/{iata}

  An airport's punctuality: today's board against the average, the local-hour curve, the airline ranking, and the count of what the sample floor set aside.

• /api/airport/{iata}/conditions

  The airport forecast (TAF) and the active en-route warnings (SIGMET) within its radius. Separate from the airport page, because a warning lives for hours, not thirty days.

  radius_km

• /api/aircraft/{reg}/activity

  One aircraft's thirty-day record: how many flights each day and from which airports. A zero day means a day we looked and saw nothing.

• /api/aircraft/{reg}/distance

  The total distance Asemanjoo has observed from one airframe — not that aircraft's lifetime distance. The observation window and the number of un-aggregated days come in this same response, because the number cannot be read without them.

• /api/aircraft/{reg}/utilization

  The utilisation of one airframe: mean flight hours per day and mean ground turnaround between two flights, over the given window. An aircraft with recorded flights on fewer than five different days gets no number.

  days

• /api/airline/{iata}/fleet-utilization

  The same utilisation, for an airline's whole fleet: one row per registration, plus the fleet average over those that reached the sample floor.

  days, limit

• /api/airline/{iata}/fleet

  The aircraft we have seen for this airline — not the official fleet — with whether each is in the air right now or on the ground, and if on the ground, when and where it was last seen. A registration parked for the whole window is not in this list.

  days, limit

• /api/airline/{iata}/operated-by

  For flights sold under this airline's code, their real operator when it differs from the airline itself — a sign of a wet lease. Continue reading it with `/api/operator/{icao}`.

  days

• /api/operator/{icao}

  The real operator of a fleet instead of the ticket seller — the same shape as `/api/airline/{iata}`, but based on who actually operated the aircraft, not on which code the ticket was sold under.

  days

• /api/airline/{iata}/fleet-wikidata

  A second, independent source for the same question: the airframes Wikidata (not our own receivers) knows for this airline. This is not the official fleet either — Wikidata records only notable aircraft one by one, not a complete fleet, so the count is a floor, not a ceiling.

  limit

• /api/type/{code}/sectors

  What distances this aircraft type covers: the median, the spread, and fixed distance bands so that two types can be compared.

• /api/type/{code}/live

  A right-now census of this type: how many airframes of this type are seen in the sky at this moment — from the server's own live table, not from the browser map's count, which is bounded by the connection cap.

• /api/emergency/history

  Archive of the emergency squawks (7500/7600/7700) with the start of the record. The end of an event means the aircraft stopped sending that code — it says nothing about its fate.

• /api/digest/today

  Today's summary since midnight in Tehran: the flight count, the busiest route, the longest and shortest observed flight, and today's emergency codes. Any section can be empty — meaning we caught nothing today, not that the query failed.

• /api/data-health

  What the site knows about itself: the share of flights with a track, an altitude and a registration, the collector's availability, and each source's share. “Not measured” and “healthy” are two different answers.

  days

• /api/iran/today

  Iran's sky from Tehran midnight to this moment. What we saw, not what flew — coverage is not uniform.

• /api/iran/airports

  Iran's airports with runway, elevation and navaids. The reference columns are kept separate from the observed column.

• /api/iran/network

  Domestic city pairs in order of flights seen, the two directions counted as one. The sample floor and what it removed are both returned.

• /api/iran/fleet

  Iranian-registered aircraft we have seen. “Not seen” means we did not hear it; no grounding is inferred from it.

• /api/wx/wind

  Wind and temperature measured by the aircraft themselves, cell by cell at one degree — not a forecast. Three separate wind numbers come back: the vector direction (the mean of 350 and 010 degrees is 000, not 180), the scalar speed, and the vector magnitude, which says how steady the wind was. A cell where nobody measured any wind is “unknown”, not “calm”.

  south, north, west, east, band, hours, min_wind, limit

• /api/gnss/integrity

  Where aircraft have reported losing their satellite position, on a half-degree grid. Every count comes with its own denominator; a cell with zero readings has no rate and is not clear sky, it is our blindness. coverage says how many hours of history this table has at all.

  south, north, west, east, hours, min_readings, limit

• /api/gnss/integrity/series

  The same numbers, hour by hour instead of cell by cell. An hour with no flight in the box has no row at all — it is a gap, not a zero trough; filling it would draw a collector outage as a sudden improvement in the sky.

  south, north, west, east, hours

• /api/flight/{flight_id}/intent

  Altitude and the code the pilot selected over the course of one flight, one row per change. A flight that does not exist gets a 404 and an existing flight with no events gets an empty list — so that “we heard nothing” does not become “there is no such flight”.

  limit

• /api/airport/{iata}/stand

  The nearest mapped stand to a point on the ground. It is an estimate, not an assignment: no source says which stand the aircraft is on. Outside the radius the answer is null, not the nearest stand anywhere. Geometry from OpenStreetMap and under ODbL.

  lat, lon, max_m

• /api/airport/{iata}/stand/by-ref

  The location of the parking stand from the gate or stand number written in the flight schedule. It is a name match, not a distance guess; no exact match means stand equals null, not the nearest stand. Geometry from OpenStreetMap and under ODbL.

  ref

• /api/military

  Flights that the receiver network's airframe database has classified as military. This is the upstream source's classification, not Asemanjoo's judgement, and it is not merged with the callsign guess and the aircraft-type prefix in the map filter. It is global and has no geographic filter. An empty column is “unknown”, not zero — an unknown route is normal in this list. [[E-284]]: each row additionally carries block_country and block_military — an independent signal from the 24-bit ICAO address range, separate from the main column and unmerged; block_basis explains it.

  days, limit

• /api/coverage/grid

  A map of our own observation coverage: each 5×5 degree cell with its number of recorded rows, its number of unique aircraft and a label of “no coverage/sparse/dense”. A cell with no record in this window is “no coverage”, not “no traffic” — an absent receiver and an absent flight cannot be told apart, and this query does not count the two as one. sparsest names the ten sparsest cells.

  hours

• /api/versions

  The versions this service answers on, which one is current, and each one's deprecation or sunset date (null until it is set). A client that is not updated in step with the service should call under the current version's prefix: under /api/v1/ fields are added, but not removed, and their type does not change. The path without a prefix is the same implementation but carries no such commitment, and is marked stable: false in this same response.

These addresses answer too, but they are not a public interface: they are either operational probes, or their answer is tied to your session, or their shape belongs to our own map and changes with it. Do not build anything on them.

• /api/healthAn operational check; it is for monitoring the service, not for data.
• /api/health/liveLiveness probe for the container.
• /api/health/readyReadiness probe for the load balancer.
• /api/health/deepA deep check of the dependencies; it is expensive and written for the operator.
• /api/status-historyAn operational check; it is the availability history of the service itself (H-35), not data about flights — behind /status, like /api/health.
• /api/ops/metricsPrometheus metrics, for monitoring.
• /api/noticeThe site's own site-wide message; its content is our decision, not data.
• /api/color-themeTheme and colour settings for the map's user interface; it is for the site's front end, not data.
• /api/paletteThe interface's default livery, chosen by the operator; like /api/color-theme it is the site's own appearance decision, not data about flights.
• /api/content/{slug}The text block of a static page (K-29); it is only for embedding in the very page that reads this slug, not independent data.
• /api/glossaryThe panel's additions and corrections to the static glossary (K-30); it is only for the server-side merge in `/glossary`.
• /api/faqQuestions added from the panel (K-31); it exists only for the server-side merge into `/faq`.
• /api/marksIts response depends on the signed-in user's session and means nothing to anyone else.
• /api/streamThe SSE stream for our own map; the shape of its rows changes with the map and we have promised nothing about its stability.
• /api/sitemapBuilt for search engines.
• /api/sitemap/{name}The same, section by section.
• /api/public/coverage/gridA mirror of the same `/api/coverage/grid` under the versioned, publicly documented subset (G-143) — it is described in “/api-docs”, not here, so that one dataset is not documented twice.
• /api/public/sourcesA mirror of the same `/api/sources` under the same public subset — described in “/api-docs”.
• /api/public/openapi.jsonThe OpenAPI document of the public subset itself; it is structure, not data.
• /api/public/docsA Swagger UI for that same document; it is a page, not data.

If you want a ready-made roll-up and not a live query, The downloads page It gives the same data in CSV form and says what we have deliberately left out. The list of upstream sources is also in The data sources page .