Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Country profiles
The automatic request and upload interface support six hand-written receiver regions and generated envelopes for every other country and territory (below):
| Country | Coverage | Envelope: west, south, east, north | Search CRS | Receiver region |
|---|---|---|---|---|
US |
conus |
-125, 24, -66, 50 |
EPSG:5070 |
Existing CONUS rectangle |
DE |
germany |
5.5, 47, 15.5, 55.2 |
EPSG:32632 |
BKG VG250 Germany land polygon inside the envelope |
ES |
spain |
-18.2, 27.5, 4.5, 43.9 |
EPSG:6933 |
Spain and territories bounding envelope; no country polygon |
FR |
france |
-5.5, 41.2, 10, 51.2 |
EPSG:2154 |
Metropolitan France including Corsica bounding envelope; no country polygon |
IT |
italy |
6.6, 35.4, 18.6, 47.1 |
EPSG:7794 |
Italy including Sicily, Sardinia and Lampedusa bounding envelope; no country polygon |
NO |
norway |
4.0, 57.9, 31.2, 71.2 |
EPSG:3035 |
Mainland Norway bounding envelope; no country polygon |
The envelope limits optional rectangular subsets. Germany's envelope includes foreign territory; the land polygon removes those receiver locations before terrain sampling or scoring. Islands, exclaves and polygon holes are preserved. The boundary is generalized geographic data, not a survey of a microphone site. Spain uses an outer envelope covering mainland Spain and its island territories. France covers mainland France and Corsica, excluding overseas departments and territories, with a Lambert-93 metric search grid. Italy covers the mainland, Sicily, Sardinia and the Pelagie islands with the national RDN2008 / Italy zone (E-N) transverse Mercator grid; San Marino, Vatican City and parts of neighboring countries and the sea fall inside its envelope. Mainland Norway uses ETRS89 / LAEA Europe (EPSG:3035), with a maximum scale error of 1.47% and angular distortion of 2.1 degrees over its envelope. UTM 33N has a 1.1% scale error but its EPSG area of use does not cover the whole mainland. Norway's envelope also includes large parts of Sweden, Finland and Russia, and the sea. These four profiles do not apply country land masks: their envelopes include sea and neighboring countries. Use explicit bounds that describe the intended receiver area. Aircraft outside the receiver bounds remain eligible when they are within the acoustic search margin. Country support does not establish localization accuracy.
All other countries and territories
Every other country or territory with an ISO 3166-1 alpha-2 code has a generated
profile: --country RS, "search":{"country":"LB"}, or the browser selector,
which groups profiles by continent. The coverage name is the lowercase English
name with underscores (for example serbia, lebanon, south_korea); the
capabilities response lists every profile with its continent, envelope and CRS.
The rows in src/dopplergeist/world_profiles.py are generated by
scripts/build_world_profiles.py from Natural Earth 1:10m Admin 0 countries
v5.1.2 (public domain). Each envelope covers the largest land part and every
part within 500 km of it, padded by 0.05 degrees, so remote overseas territories
(for example the Azores, Galapagos or Svalbard) are not included. Russia's
envelope stops at 180 E, because antimeridian crossing is unsupported.
Antarctica has no profile. Norway is left to its hand-written profile (#414).
The CRS is the EPSG projected CRS whose area of use contains the envelope with the smallest maximum point-scale error over it, restricted to datums within 5 m of WGS 84 that round-trip exactly. When no EPSG CRS keeps that error within 2%, for large countries such as China, Russia, Canada, Brazil or Australia, a WGS 84 Lambert azimuthal equal-area, Lambert conformal conic or transverse Mercator projection centred on the envelope is used (a PROJ string rather than an EPSG code). The recorded maximum error is 3.4% (Russia), 2.4% (China), and 2% or less elsewhere; it affects metric grid spacing and refinement radii, not the geodetic ECEF propagation. Like Spain, France and Italy, these envelopes include sea and neighboring countries and apply no land mask: pass explicit bounds for the intended receiver area. A profile does not establish flight-data coverage or localization accuracy in that country.
Africa: DZ Algeria, AO Angola, BJ Benin, BW Botswana, IO British Indian Ocean Territory, BF Burkina Faso, BI Burundi, CM Cameroon, CV Cape Verde, CF Central African Republic, TD Chad, KM Comoros, CD Democratic Republic of the Congo, DJ Djibouti, EG Egypt, GQ Equatorial Guinea, ER Eritrea, SZ Eswatini, ET Ethiopia, TF French Southern and Antarctic Lands, GA Gabon, GH Ghana, GN Guinea, GW Guinea-Bissau, HM Heard Island and McDonald Islands, CI Ivory Coast, KE Kenya, LS Lesotho, LR Liberia, LY Libya, MG Madagascar, MW Malawi, ML Mali, MR Mauritania, MU Mauritius, MA Morocco, MZ Mozambique, NA Namibia, NE Niger, NG Nigeria, CG Republic of the Congo, RW Rwanda, SH Saint Helena, SN Senegal, SC Seychelles, SL Sierra Leone, SO Somalia, ZA South Africa, SS South Sudan, SD Sudan, ST São Tomé and Príncipe, TZ Tanzania, GM The Gambia, TG Togo, TN Tunisia, UG Uganda, EH Western Sahara, ZM Zambia, ZW Zimbabwe.
Asia: AF Afghanistan, AM Armenia, AZ Azerbaijan, BH Bahrain, BD Bangladesh, BT Bhutan, BN Brunei, KH Cambodia, CY Cyprus, TL East Timor, GE Georgia, HK Hong Kong, IN India, ID Indonesia, IR Iran, IQ Iraq, IL Israel, JP Japan, JO Jordan, KZ Kazakhstan, KW Kuwait, KG Kyrgyzstan, LA Laos, LB Lebanon, MO Macau, MY Malaysia, MV Maldives, MN Mongolia, MM Myanmar, NP Nepal, KP North Korea, OM Oman, PK Pakistan, PS Palestine, CN People's Republic of China, PH Philippines, QA Qatar, SA Saudi Arabia, SG Singapore, KR South Korea, LK Sri Lanka, SY Syria, TW Taiwan, TJ Tajikistan, TH Thailand, TR Turkey, TM Turkmenistan, AE United Arab Emirates, UZ Uzbekistan, VN Vietnam, YE Yemen.
Europe: AL Albania, AD Andorra, AT Austria, BY Belarus, BE Belgium, BA Bosnia and Herzegovina, BG Bulgaria, HR Croatia, CZ Czech Republic, DK Denmark, EE Estonia, FO Faroe Islands, FI Finland, GI Gibraltar, GR Greece, GG Guernsey, HU Hungary, IS Iceland, IE Ireland, IM Isle of Man, JE Jersey, XK Kosovo, LV Latvia, LI Liechtenstein, LT Lithuania, LU Luxembourg, MT Malta, MD Moldova, MC Monaco, ME Montenegro, NL Netherlands, MK North Macedonia, PL Poland, PT Portugal, RO Romania, RU Russia, SM San Marino, RS Serbia, SK Slovakia, SI Slovenia, SE Sweden, CH Switzerland, UA Ukraine, GB United Kingdom, VA Vatican City, AX Åland.
North America: AI Anguilla, AG Antigua and Barbuda, AW Aruba, BB Barbados, BZ Belize, BM Bermuda, VG British Virgin Islands, CA Canada, KY Cayman Islands, CR Costa Rica, CU Cuba, CW Curaçao, DM Dominica, DO Dominican Republic, SV El Salvador, GL Greenland, GD Grenada, GT Guatemala, HT Haiti, HN Honduras, JM Jamaica, MX Mexico, MS Montserrat, NI Nicaragua, PA Panama, PR Puerto Rico, BL Saint Barthélemy, KN Saint Kitts and Nevis, LC Saint Lucia, MF Saint Martin, PM Saint Pierre and Miquelon, VC Saint Vincent and the Grenadines, SX Sint Maarten, BS The Bahamas, TT Trinidad and Tobago, TC Turks and Caicos Islands, UM United States Minor Outlying Islands, VI United States Virgin Islands.
Oceania: AS American Samoa, AU Australia, CK Cook Islands, FM Federated States of Micronesia, FJ Fiji, PF French Polynesia, GU Guam, KI Kiribati, MH Marshall Islands, NR Nauru, NC New Caledonia, NZ New Zealand, NU Niue, NF Norfolk Island, MP Northern Mariana Islands, PW Palau, PG Papua New Guinea, PN Pitcairn Islands, WS Samoa, SB Solomon Islands, TO Tonga, TV Tuvalu, VU Vanuatu, WF Wallis and Futuna.
South America: AR Argentina, BO Bolivia, BR Brazil, CL Chile, CO Colombia, EC Ecuador, FK Falkland Islands, GY Guyana, PY Paraguay, PE Peru, GS South Georgia and the South Sandwich Islands, SR Suriname, UY Uruguay, VE Venezuela.
Requests and commands
dopplergeist analyze recording.mp3 --country DE --jobs jobs --online \
--start-utc "$RECORDING_START_UTC_MIN" --end-utc "$RECORDING_START_UTC_MAX" \
--time-source 'Evidence establishing the recording-start interval'
Use --country FR for metropolitan France, including Corsica, --country IT
for Italy, or --country NO for mainland Norway, or select the country in the browser's country selector. The upload API accepts
"search":{"country":"DE"}, "search":{"country":"ES"} or
"search":{"country":"FR"}, "search":{"country":"IT"} or "search":{"country":"NO"}. It also accepts
the matching coverage names germany, spain, france, italy and norway. A normalized request records the coverage;
an explicitly supplied country is normalized to uppercase. If both are supplied,
they must agree. bounds_wsen and --bounds narrow the selected profile. They
must be an independently justified prior, not the evaluation location.
Omitting country preserves the previous CONUS behavior. Old requests/results without a country field remain readable. An older service advertises no country catalog, so the new browser offers only CONUS and sends the legacy request shape.
The configured research command also accepts a top-level country or a search
object. A supplied grid.crs must match the country profile, and grid.bounds
must agree with any search.bounds_wsen. That command retains its existing
configured-event and uncertified-coverage limitations.
Germany boundary acquisition
The first online German search obtains the country layer vg250:vg250_sta,
filtered to GF=4, from the official BKG WFS.
It requests EPSG:25832 so the original ETRS89 / UTM 32N geometry is retained.
Receiver coordinates are transformed into that CRS for point-in-polygon tests.
The search grid and reported projected coordinates use EPSG:32632 consistently.
The WFS product advertises the 2025-01-01 dataset. The pinned land feature has
object ID DEBKGVG200000CKM and BEGINN=2025-04-11Z; it is not described as the
separate 2026 download product. Its canonical geometry, properties and CRS have
SHA-256 b5e9276fe37ca1c0d65b4542a075cc246e97194ed70d3259b0d7900ad944a1d3.
The response's request timestamp is excluded from that content identity.
The validated feature is cached at
CACHE_ROOT/geography/de-vg250-b5e9276fe37ca1c0.json. The download is limited to
8 MiB and written atomically after validation. Offline searches require this
cache entry. Copying this entry to another machine preserves the same boundary.
Missing, damaged or changed source data produce an explicit data-unavailable
outcome. A future WFS update does not silently replace the pinned geometry;
review its data and update the pin deliberately.
No source simplification is applied. The source's 110 polygon components and their holes remain intact. Prepared vector predicates avoid creating a separate geometry object for every receiver. The mask is serialized to each search worker.
Search and checkpoint behavior
The mask applies to serial and parallel coarse tiles, fine tiles, research grids, continuous refinement and every sensitivity scenario. A masked-out continuous proposal never reaches terrain sampling or acoustic scoring. A valid seed remains available when optimization proposes an invalid location. A refinement whose explored radius meets the country boundary is marked boundary-limited.
Before automatic flight acquisition, a bounded geographic check establishes at
least one eligible coarse-grid receiver. Foreign-only selections and small land
selections containing no coarse-grid point return needs_input with a specific
area or grid-resolution explanation. An inconclusive bounded check stops with an
explicit limitation; it does not report an empty area or a completed flight search.
The full-country check uses land-component probes rather than enumerating the
national grid.
Aircraft are not country-masked. Automatic acquisition retains full historical trajectories, and tile queries include the existing audible-range border margin. Archive absence or incomplete trajectory/model support remains visible.
German search identities include the boundary content, source, selected CRS and Shapely version. Changing those inputs cannot reuse incompatible search results. Legacy CONUS requests retain their meaning, but a new code revision does not automatically make an old source-pinned checkpoint resumable. Preserve the old producer or use a separately verified migration; no identity bypass is added.
Geographic checks
python scripts/check_country_profiles.py --online --cache-root /tmp/dopplergeist-geography
python scripts/check_country_profiles.py --cache-root /tmp/dopplergeist-geography
The check uses the actual pinned BKG geometry, named geographic points, country boundary grids, mainland France and Corsica grids, empty-area checks and worker serialization. It generates no audio or flight tracks. These are software/geography checks, not an acoustic localization benchmark.
Boundary license and source
© BKG 2026, dl-de/by-2-0. Data sources. Official product metadata.
Processing: selection of the land feature and coordinate transformation for receiver tests; no polygon simplification. Boundary data retains its source license. The application code retains the repository's PolyForm license.