Public briefing sources¶
The briefing sources integration reads three fixed public keyless APIs and returns the maintained four-component DataRef contract. It never takes model prose as a source value, reads a provider credential or scrapes HTML.
Create PublicSourceHTTP with an optional injected httpx transport and clock, then PublicBriefingSources with that client. Call flight(callsign), weather(latitude, longitude, location=airport_code, arrival=aware_datetime), market(currencies), or arrival_timeline(flight_reference, transfer_minutes=the_explicitly_stated_number, meeting_time=aware_datetime). Close the client after use. read_briefing composes all four references and uses the route's destination coordinates for the weather request.
Only api.met.no, api.adsb.lol and data-api.ecb.europa.eu are allowed, on HTTPS 443 and fixed documented path shapes. Redirects, userinfo, nonstandard ports, arbitrary URLs and environment proxies are refused. The client serialises requests, sends an identifying User-Agent, caches each request for at least 60 s and respects MET's later Expires header. HTTP429 establishes Retry-After cooldown with no automatic retry. Each client run has a 20-request per-host rolling ten minute budget and each response is limited to 1 MiB with a 10 s inactivity timeout and a monotonic deadline checked on every unbuffered network chunk. Keep one shared client for the service run; do not create new clients to evade the rolling budget, source cooldown or cache.
MET Norway hourly forecasts carry CC BY4.0 attribution. Missing precipitation probability stays null. ADSB.lol position data carry ODbL1.0 attribution and routes credit Virtual Radar Server standing data, CC0. Positions older than120s, missing/zero ground speed, ambiguous multi-leg routes or an unconfirmed route produce an empty unavailable reference. The arrival estimate is computed from position, speed and great-circle distance: it is not an airline time. No scheduled date, terminal or airline status is invented.
The timeline uses only that validated estimate, the traveller's stated transfer and meeting time. Transfer is explicitly an ASSUMPTION. ECB daily EUR reference rates retain their actual publication date and say daily reference rate, not a live quote. Changes use Decimal arithmetic rounded half-even to six decimal places; a missing previous observation leaves change null. Source: ECB statistics; data are freely available from ECB. Derived changes are identified. Partial ECB replies make the whole market card unavailable. No stock prices, invented rows, today-stamped holidays or fake midnight publication time are supplied.
Provider failures return an error DataRef with empty payload and a fixed plain reason. An expired value is never a successful fallback for a failed refresh. Personal aircraft-owner, passenger and crew fields are discarded before cache custody. Each displayed value needs the renderer's honest provenance and freshness labels; the sources do not implement a second HTML renderer.
The recorded smoke contains one real forecast, an empty aircraft response and an unavailable ECB transport. Successful synthetic offline vectors test behaviour; they are not live-source or full-demo proof. Independent consuming fresh-clone and graphical acceptance remain separate.
The ADSB route lookup accepts HTTP 200 or 201 Created for the guarded
POST /api/0/routeset only. GET responses still require HTTP 200; redirects,
202 Accepted and 204 No Content remain unavailable. Ops observed the 201
status on a real route lookup; regression payloads remain synthetic.
A caller may pass StatedDestination(code, latitude, longitude) resolved from
its own versioned local airport table to flight or read_briefing. Core
validates the code and finite coordinate ranges before access. It does not
look up a destination or contact a new host. A stated destination overrides a
conflicting source route, with a visible disagreement and the explicit label
"destination stated by traveller". The estimate and timeline name this input;
they remain COMPUTED, never an airline schedule.
An empty or malformed route no longer discards a valid position. The flight card keeps its validated altitude, speed and position age in the existing provider-facts status string and says "Route not provided by the source". Without a destination, route and estimate stay not provided; dependent weather and timeline stay unavailable with that fixed reason. Real position failures still return an empty unavailable reference. These offline cases use synthetic payloads, not a claim that a live journey has been accepted.
Discover flights from published routes and observed positions¶
PublicBriefingSources.find_flights reads aircraft within 250 nautical miles of
an explicitly supplied metro point. The caller supplies the metro's airport
codes and a local, versioned dict[str, PublishedRoute] with a real ISO calendar
publication date. This is a public unauthenticated read with one guarded GET to
api.adsb.lol/v2/point/<latitude>/<longitude>/250; it never makes a routeset
request for each aircraft and adds no host or dependency.
The result is a FlightSearch, not a fifth widget type. It contains up to five
FlightCandidate values: observed callsign, published airline/origin/destination,
observed altitude, position age and coordinates. The caller must show the route
date and exact label headed to New York per published route data; position live
when the supplied city is New York. source retains attribution. A route table
is historical published data, not a current filed flight plan or airline
schedule. A partial table limits coverage; never list unmatched aircraft as
headed to that destination or claim the search covers all flights worldwide.
Only airport-matched routes are retained. Ground, stale, invalid, ambiguous or out-of-radius aircraft are excluded. For point searches the client filters every aircraft in the response, bounded by the existing 1 MiB response limit. Only six position fields survive before cache custody; registration and owner fields are discarded. Other aircraft endpoints retain their existing projection limit. Provider cache and rolling request budgets are shared with the other briefing readers; cached positions are checked again for age at each search. Callsigns use the standing data's ICAO leading-zero normalization for lookup while preserving the actual observed callsign in results. An IATA-only callsign with no matching route is not guessed.
An empty successful search has candidates == (), error is None and the fixed
message No flights found. A provider or input failure has a plain, value-free
error; it must not be reported as a successful empty search. Route data are
supplied by the application and are not downloaded or bundled by Core.
partial is true when the provider reports truncated: true, partial: true,
or a total greater than its returned aircraft count. Such results may contain
candidates, but their message warns that the search is partial, even when no
matching candidates survive. A response exceeding 1 MiB is refused with both
partial == True and a fixed error; no incomplete JSON is parsed. Absence of a
provider truncation signal cannot establish global completeness. Always show
the caller-owned route table's date and limited coverage too.