api.openathena.com

OpenAthena™ cloud RESTful API

Provided By: 𝚹 Theta Informatics LLC

This cloud API enables other applications to use OpenAthena's terrain-raycast method for geo-locating any point within drone imagery.

OpenAthena™ can instantly and precisely geolocate any single pixel of a single drone image. It does this by combining drone camera position and orientation data with a digital twin of terrain elevation.

OpenAthena obtains precise ground coordinates for any single drone image pixel without the need for a laser-rangefinder using its novel terrain-raycast technique. This is extremely useful for use of drones for search and rescue, public safety, defense technology, and more.

Video Demo: https://youtu.be/it9khfq-IeQ

For more information, visit https://OpenAthena.com

To obtain an API key for testing and evaluation, please contact info@theta.limited

OpenAthena API Summary:

RESTful API where drone camera position, orientation, and pixel of interest are fed as inputs, target location is output
Use GET, POST, PUT, DELETE methods
JSON object as params for some requests and all responses
You must append a valid API key in all query strings, e.g. add ?apikey=YOUR_API_KEY_HERE

For best results, please calibrate your drone's magnetometer (compass sensor) in an area free of magnetic interference and less than 300 km of your area of operations!

Accurate results require a drone-to-target slant angle of at least 15° or more downwards from the horizon (straight forwards).

Examining and Using the Digital Elevation Model Cache

Show

OpenAthena Core analyzes drone image metadata using elevation data automatically downloaded from OpenTopography.org. By default, OpenAthena Core downloads data from the USGS 3DEP dataset for areas in the U.S., EU_DTM for Western Europe, and the Copernicus GLO-30 DSM (COP30) for areas elsewhere on Earth. The downloaded elevation data, or DEMs, are stored in a demcache directory (configured via openathenacore.properties or via command-line argument) and are cached in memory.

Other datasets are now supported as well. To specify a different elevation dataset, set and pass the dataset parameter, where appropriate, in the API.

dataset parameter values

Value Description
SRTMGL1 Shuttle Radar Topography Mission Global 30m
3DEP USGS 1/3 arc-second Digital Elevation Model 10m
DTED2 DTED2+ 1 arc sec 30m
EUDTM Continental Europe Digital Terrain Model 30m
COP30 Copernicus Global DSM 30m
DEFAULT Default/SRTMGL1 30m
MARITIME Use Mean Sea Level instead of any terrain height (use over oceans)

Value	Description
`SRTMGL1`	Shuttle Radar Topography Mission Global 30m
`3DEP`	USGS 1/3 arc-second Digital Elevation Model 10m
`DTED2`	DTED2+ 1 arc sec 30m
`EUDTM`	Continental Europe Digital Terrain Model 30m
`COP30`	Copernicus Global DSM 30m
`DEFAULT`	Default/SRTMGL1 30m
`MARITIME`	Use Mean Sea Level instead of any terrain height (use over oceans)

GET /api/v1/openathena/dem (return DEM cache entries)

Parameters

None

Responses

http code content-type response
200 application/json JSON array of DEM cache entries; key is cache
404 application/json Invalid DEM query

http code	content-type	response
`200`	`application/json`	JSON array of DEM cache entries; key is `cache`
`404`	`application/json`	Invalid DEM query

GET /api/v1/openathena/dem/{name} (return cache entry for specific DEM filename)

Parameters

name type data type description
{name} required string digital elevation model filename

name	type	data type	description
`{name}`	required	string	digital elevation model filename

Responses

http code content-type response
200 application/json JSON object containing DEM cache entry; key is cacheEntry
404 application/json DEM entry not found

http code	content-type	response
`200`	`application/json`	JSON object containing DEM cache entry; key is `cacheEntry`
`404`	`application/json`	DEM entry not found

GET /api/v1/openathena/dem?lat={lat}&lon={lon} (Search for and retrieve a cache entry for a particular lat,lon location)

Parameters

name type data type description
lat required float/decimal latitude e.g. 33.837470333333336
lon required float/decimal longitude e.g. -84.52259847222223

name	type	data type	description
`lat`	required	float/decimal	latitude e.g. 33.837470333333336
`lon`	required	float/decimal	longitude e.g. -84.52259847222223

Responses

http code content-type response
200 application/json JSON object containing matching DEM cache entry; key is cacheEntry
404 application/json Unable to find matching cache entry

http code	content-type	response
`200`	`application/json`	JSON object containing matching DEM cache entry; key is `cacheEntry`
`404`	`application/json`	Unable to find matching cache entry

GET /api/v1/openathena/dem/count (Get number of cache entries)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing number of entries; key is demCacheCount
404 application/json Invalid DEM query

http code	content-type	response
`200`	`application/json`	JSON object containing number of entries; key is `demCacheCount`
`404`	`application/json`	Invalid DEM query

GET /api/v1/openathena/dem/date (Get date/time of last cache refresh)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing string date/time of cache refresh; key is demCacheDate
404 application/json Invalid DEM query`

http code	content-type	response
`200`	`application/json`	JSON object containing string date/time of cache refresh; key is `demCacheDate`
`404`	`application/json`	Invalid DEM query`

GET /api/v1/openathena/dem/bytes (Get size of cache)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing size in bytes of cache, key is demCacheSize
404 application/json Invalid DEM query

http code	content-type	response
`200`	`application/json`	JSON object containing size in bytes of cache, key is `demCacheSize`
`404`	`application/json`	Invalid DEM query

DELETE /api/v1/openathena/dem/{name} (Delete a DEM cache entry; admin only)

Parameters

name type data type description
{name} required string filename (w/o full path) of cache entry to delete (e.g. DEMxxx.cop30)

name	type	data type	description
`{name}`	required	string	filename (w/o full path) of cache entry to delete (e.g. DEMxxx.cop30)

Responses

http code content-type response
200 application/json DEM cache entry successfully deleted
404 application/json Invalid DEM operation

http code	content-type	response
`200`	`application/json`	DEM cache entry successfully deleted
`404`	`application/json`	Invalid DEM operation

POST /api/v1/openathena/dem?lat={lat}&lon={lon}&len={len} (Fetch a new DEM centered at lat,lon size len by len meters.)

Parameters

name type data type description
lat required float/decimal latitude e.g. 33.837470333333336
lon required float/decimal longitude e.g. -84.52259847222223
len required integer len (meters) of side of bounding box (e.g. 10000)
dataset optional string dataset to use: SRTM, THREEDEP, COP30, EUDTM, DEFAULT

name	type	data type	description
`lat`	required	float/decimal	latitude e.g. 33.837470333333336
`lon`	required	float/decimal	longitude e.g. -84.52259847222223
`len`	required	integer	len (meters) of side of bounding box (e.g. 10000)
`dataset`	optional	string	dataset to use: SRTM, THREEDEP, COP30, EUDTM, DEFAULT

Responses

http code content-type response
200 application/json returned cache filename
404 application/json Invalid DEM query

http code	content-type	response
`200`	`application/json`	returned cache filename
`404`	`application/json`	Invalid DEM query

POST /api/v1/openathena/dem/alt?lat={lat}&lon={lon}[&dataset={string}] (Return the terrain alt for lat,lon; may induce a DEM download)

Parameters

name type data type description
lat required float/decimal latitude e.g. 33.837470333333336
lon required float/decimal longitude e.g. -84.52259847222223
dataset optional string Optional elevation dataset (see dataset valid values above)

name	type	data type	description
`lat`	required	float/decimal	latitude e.g. 33.837470333333336
`lon`	required	float/decimal	longitude e.g. -84.52259847222223
`dataset`	optional	string	Optional elevation dataset (see `dataset` valid values above)

Responses

http code content-type response
200 application/json JSON object containing altitude info; the fields are terrainAltWGS84 terrainAltAMSL
geoidOffset demDescription
400 application/json Invalid inputs, no matching DEM, etc.

http code	content-type	response
`200`	`application/json`	JSON object containing altitude info; the fields are `terrainAltWGS84` `terrainAltAMSL`
		`geoidOffset` `demDescription`
`400`	`application/json`	Invalid inputs, no matching DEM, etc.

GET /api/v1/openathena/bulkdemdownloader/{uuid} (Return the bulk DEM downloader task associated with this uuid)

Parameters

name type data type description
uuid required string UUID e.g. f81ef2cd-4dbd-4550-bbe5-1e212b9ab12e

name	type	data type	description
`uuid`	required	string	UUID e.g. f81ef2cd-4dbd-4550-bbe5-1e212b9ab12e

Responses

http code content-type response
200 application/json JSON object containing bulk DEM downloader task info; the field is bulkdemdownloader
404 application/json Invalid UUID or no such bulk DEM downloader

http code	content-type	response
`200`	`application/json`	JSON object containing bulk DEM downloader task info; the field is `bulkdemdownloader`
`404`	`application/json`	Invalid UUID or no such bulk DEM downloader

GET /api/v1/openathena/bulkdemdownloader

(Return JSON array of bulk DEM downloader tasks.  Tasks include currently running, queued to run, and those previously run.)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing JSON array of bulk DEM downloader task info objects; the field is bulkdemdownloadqueue

http code	content-type	response
`200`	`application/json`	JSON object containing JSON array of bulk DEM downloader task info objects; the field is `bulkdemdownloadqueue`

POST /api/v1/openathena/bulkdemdownloader

(Create and submit a bulk DEM downloader task.  Provide opposite corners of bounding box, tile size, dataset, overlap and optional job name.)

name type data type description
none required JSON object JSON object containing image metadata

name	type	data type	description
`none`	required	JSON object	JSON object containing image metadata

POST Body JSON Object Key/Value Pairs

key name type data type description example
len required float length in meters of tile square 25_000
lat1 required float/decimal latitude of corner1 59.78810595075987
lon1 required float/decimal longitude of corner1 -50.51953142881393
lat2 required float/decimal latitude of corner2 64.80844051498411
lon2 required float/decimal longitude of corner2 -40.59374874830245
dataset required string elevation dataset (see dataset valid values above) THREEDEP
overlap required float 0.0 < Percentage overlap < 1.0 0.20
jobname optional string optional short job description or name Area download

key name	type	data type	description	example
`len`	required	float	length in meters of tile square	25_000
`lat1`	required	float/decimal	latitude of corner1	59.78810595075987
`lon1`	required	float/decimal	longitude of corner1	-50.51953142881393
`lat2`	required	float/decimal	latitude of corner2	64.80844051498411
`lon2`	required	float/decimal	longitude of corner2	-40.59374874830245
`dataset`	required	string	elevation dataset (see `dataset` valid values above)	THREEDEP
`overlap`	required	float	0.0 < Percentage overlap < 1.0	0.20
`jobname`	optional	string	optional short job description or name	Area download

Responses

http code content-type response
201 application/json JSONobject containing result; bulk DEM download task created
400 application/json Bad request due to invalid task parameters

http code	content-type	response
`201`	`application/json`	JSONobject containing `result`; bulk DEM download task created
`400`	`application/json`	Bad request due to invalid task parameters

POST /api/v1/openathena/bulkdemdownloader/{uuid}/stop (Stop a bulk DEM downloader task. Even if successful, already queued DEM tile downloads will complete.)

Parameters

name type data type description
uuid required string UUID e.g. f81ef2cd-4dbd-4550-bbe5-1e212b9ab12e

name	type	data type	description
`uuid`	required	string	UUID e.g. f81ef2cd-4dbd-4550-bbe5-1e212b9ab12e

Responses

http code content-type response
202 application/json JSONobject containing result; bulk DEM download task created
200 application/json Unable to stop job; it may not exist or may already be stopped.

http code	content-type	response
`202`	`application/json`	JSONobject containing `result`; bulk DEM download task created
`200`	`application/json`	Unable to stop job; it may not exist or may already be stopped.

Examining Drone Information Database

Show

GET /api/v1/openathena/drone?search={string} (Search for a drone info database entry)

Parameters

name type data type description
string required string drone search string (e.g. dji or fisheye)

name	type	data type	description
`string`	required	string	drone search string (e.g. dji or fisheye)

Responses

http code content-type response
200 application/json JSON array of matching drones
404 application/json Invalid or no search string

http code	content-type	response
`200`	`application/json`	JSON array of matching drones
`404`	`application/json`	Invalid or no search string

GET /api/v1/openathena/{makeModel} (Get entries matching make/model string)

Parameters

name type data type description
makeModel required string make/model string to match

name	type	data type	description
`makeModel`	required	string	make/model string to match

Responses

http code content-type response
200 application/json JSON array of matching drones
404 application/json Invalid drone query

http code	content-type	response
`200`	`application/json`	JSON array of matching drones
`404`	`application/json`	Invalid drone query

GET /api/v1/openathena/drone/count (Get number of entries in the drone info database)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing number of entries; key is count
404 application/json Invalid drone query

http code	content-type	response
`200`	`application/json`	JSON object containing number of entries; key is `count`
`404`	`application/json`	Invalid drone query

GET /api/v1/openathena/drone/date (Get the date of the drone information database)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing date of drone info database
404 application/json Invalid drone query

http code	content-type	response
`200`	`application/json`	JSON object containing `date` of drone info database
`404`	`application/json`	Invalid drone query

Analyzing Drone Images

Show

For geolocating a specific pixel within a drone image, the drone image itself does not need to be uploaded. Instead, the required camera position and orientation metadata is provided via the POST method and sent to the OpenAthena Core API server. All values should be passed via JSON as quoted strings even if they are floats, ints, etc.

For altitude, either GPS Altitude (defined as height above the WGS84 ellipsoid [HAE] in meters) or MSL Altitude (defined as height above mean sea level [AMSL] in meters) must be provided. HAE and AMSL are actually two different vertical datums which are deceptively similar, but can be off as much as 30 meters from each other in a typical case. Whether the drone platform reports its altitude in HAE or AMSL depends on the flight control software and even firmware version being used. Using one incorrectly for the other will add at least 20-30 meters of targeting error to OpenAthena's terrain-raycast.

See this web page for an explainer on the difference between HAE and AMSL vertical datums for elevation.

Other datasets are now supported as well. To specify a different elevation dataset, set and pass the dataset parameter, where appropriate, in the API. (This type may also be referred to, in query parameters, as dataset.)

dataset parameter values

Value Description
SRTMGL1 Shuttle Radar Topography Mission Global 30m
3DEP USGS 1/3 arc-second Digital Elevation Model 10m
DTED2 DTED2+ 1 arc sec 30m
EUDTM Continental Europe Digital Terrain Model 30m
COP30 Copernicus Global DSM 30m
DEFAULT Default/SRTMGL1 30m
MARITIME Use Mean Sea Level instead of any terrain height (use over oceans)

Value	Description
`SRTMGL1`	Shuttle Radar Topography Mission Global 30m
`3DEP`	USGS 1/3 arc-second Digital Elevation Model 10m
`DTED2`	DTED2+ 1 arc sec 30m
`EUDTM`	Continental Europe Digital Terrain Model 30m
`COP30`	Copernicus Global DSM 30m
`DEFAULT`	Default/SRTMGL1 30m
`MARITIME`	Use Mean Sea Level instead of any terrain height (use over oceans)

OpenAthena Core bundles a database of camera calibration values (camera intrinsics) for known drone camera make and models. These camera intrinsic values are necessary for calculating the pitch and yaw angle of any off-center image pixel. OpenAthena Core references this database to find matching calibration values for the camera make and model name included in your API request.

Alternatively, if your camera make and model name are not in OpenAthena's drone models database (such as for a custom camera), you can camera inrinsics calibration values with theta's camera calibration tool and include them directly within your API request instead.

These optional parameters for camera intrinsics are documented below.

optional drone camera intrinsics

See this link for an explanation of these camera instrinsic parameters.

See this link for a link to Theta's open source camera calibration tool which calculates these values using a few dozen images taken of a B/W checkerboard calibration pattern poster. Theta has prints of this poster available for order, email info@theta.limited for details.

key name data type description example
isThermal boolean true if thermal camera; false otherwise default false
widthPixels int pixel width of full resolution camera sensor 5472
heightPixels int pixel height of full resolution camera sensor 3648
lensType string perspective or fisheye 'perspective' only supported at present
ccdWidthMMPerPixel float width of each pixel (in mm) 12.83332/5472.0
ccdHeightMMPerPixel float height of each pixel (in mm) 8.55554/3648.0
radialR1 float first radial distortion coefficient for the camera lens default is 0.0
radialR2 float second radial distorion coefficient default is 0.0
radialR3 float third radial distorion coefficient default is 0.0
tangentalT1 float first tangential distortion coefficient for the camera lens default is 0.0
tangentalT2 float second tangential distortion coefficient default is 0.0

key name	data type	description	example
`isThermal`	boolean	true if thermal camera; false otherwise	default false
`widthPixels`	int	pixel width of full resolution camera sensor	5472
`heightPixels`	int	pixel height of full resolution camera sensor	3648
`lensType`	string	perspective or fisheye	'perspective' only supported at present
`ccdWidthMMPerPixel`	float	width of each pixel (in mm)	12.83332/5472.0
`ccdHeightMMPerPixel`	float	height of each pixel (in mm)	8.55554/3648.0
`radialR1`	float	first radial distortion coefficient for the camera lens	default is 0.0
`radialR2`	float	second radial distorion coefficient	default is 0.0
`radialR3`	float	third radial distorion coefficient	default is 0.0
`tangentalT1`	float	first tangential distortion coefficient for the camera lens	default is 0.0
`tangentalT2`	float	second tangential distortion coefficient	default is 0.0

Location calculation Request

POST /api/v1/openathena/locationsimple (Return simplified geolocation of pixel within a drone image via provided metadata)

Parameters

name type data type description
none required JSON object JSON object containing image metadata

name	type	data type	description
`none`	required	JSON object	JSON object containing image metadata

POST Body JSON Object Key/Value Pairs

key name type data type description example
GPS Latitude required float latitude +- decimal degrees 33.837470333
GPS Longitude required float longitude +- decimal degrees -84.522598472
GPS Altitude semi-required float altitude in WGS84 Height Above Elipsoid (HAE) meters (see note above) 437.920107
MSL Altitude semi-required float altitude in Above Mean Sea Level (AMSL) meters according to EGM96 Geoid (see note above) 101.233
Focal Length required float focal length of image 6.72
Focal Length 35 optional float 35mm equivalent focal length 24.0
ImageWidth required int image width in pixels (scaled values are OK) 4032
ImageHeight required int image height in pixels (scaled vales are OK) 3024
Camera:Roll required float degrees roll of camera relative to ground (clockwise from camera perspective is positive) 0.0
GimbalPitchDegree required float degree pitch of gimbal or camera; measured in degrees downward from horizon 41.40
GimbalYawDegree required float compass heading in degrees; north is 0 and increasing clockwise 156.30
Camera Make required string manufacturer name of drone camera DJI
Camera Model required string model name of drone camera FC8482
Digital Zoom Ratio optional float digital zoom (centered crop) ratio, leave at 1.0 if digital crop has not been applied to image 1.0
timestamp_iso8601 optional string ISO8601 format time stamp YYYY-MM-DDTHH:mm:ss.sssZ 2026-01-25T21:28:43.123Z
xprop optional float x position of target within image frame as a proportion 0-1.0, measured from the left edge increasing rightward 0.50 is default
yprop optional float y position of target within image frame as a proportion 0-1.0, measured from the top edge increasing downwards 0.50 is default
dataset optional string Terrain elevation dataset to use for calculations, if possible COP30 (see list above)
drone camera intrinsics optional see above only needed if camera make and model not in database; see above for key names and descriptions
cottype optional string Type value to include CoT messages a-p-G (see COT specs)
cotuid optional string CoT UID to include in CoT messages OpenAthenaCore-November01-668

key name	type	data type	description	example
`GPS Latitude`	required	float	latitude +- decimal degrees	33.837470333
`GPS Longitude`	required	float	longitude +- decimal degrees	-84.522598472
`GPS Altitude`	semi-required	float	altitude in WGS84 Height Above Elipsoid (HAE) meters (see note above)	437.920107
`MSL Altitude`	semi-required	float	altitude in Above Mean Sea Level (AMSL) meters according to EGM96 Geoid (see note above)	101.233
`Focal Length`	required	float	focal length of image	6.72
`Focal Length 35`	optional	float	35mm equivalent focal length	24.0
`ImageWidth`	required	int	image width in pixels (scaled values are OK)	4032
`ImageHeight`	required	int	image height in pixels (scaled vales are OK)	3024
`Camera:Roll`	required	float	degrees roll of camera relative to ground (clockwise from camera perspective is positive)	0.0
`GimbalPitchDegree`	required	float	degree pitch of gimbal or camera; measured in degrees downward from horizon	41.40
`GimbalYawDegree`	required	float	compass heading in degrees; north is 0 and increasing clockwise	156.30
`Camera Make`	required	string	manufacturer name of drone camera	DJI
`Camera Model`	required	string	model name of drone camera	FC8482
`Digital Zoom Ratio`	optional	float	digital zoom (centered crop) ratio, leave at 1.0 if digital crop has not been applied to image	1.0
`timestamp_iso8601`	optional	string	ISO8601 format time stamp YYYY-MM-DDTHH:mm:ss.sssZ	2026-01-25T21:28:43.123Z
`xprop`	optional	float	x position of target within image frame as a proportion 0-1.0, measured from the left edge increasing rightward	0.50 is default
`yprop`	optional	float	y position of target within image frame as a proportion 0-1.0, measured from the top edge increasing downwards	0.50 is default
`dataset`	optional	string	Terrain elevation dataset to use for calculations, if possible	COP30 (see list above)
`drone camera intrinsics`	optional	see above	only needed if camera make and model not in database; see above for key names and descriptions
`cottype`	optional	string	Type value to include CoT messages	a-p-G (see COT specs)
`cotuid`	optional	string	CoT UID to include in CoT messages	OpenAthenaCore-November01-668

Responses

http code content-type response
200 application/json JSON object containing simplified geolocation information
400 application/json Location error

http code	content-type	response
`200`	`application/json`	JSON object containing simplified geolocation information
`400`	`application/json`	Location error

Returned JSON location Object Key/Value Pairs

key name data type description example
targetLat float target latitude 33.8358084243378
targetLon float target longitude -84.5207742586809
targetAltHAE float target altitude 309.8363786905352
targetDistanceMeters float distance to target 281.2324945266905
predictedCE float predicted error, meters 11.521343585384802
TLE_Cat String predicted error category CAT_2
elevationDataModel String dataset that elevation data came from Copernicus Global DSM 30m

key name	data type	description	example
`targetLat`	float	target latitude	33.8358084243378
`targetLon`	float	target longitude	-84.5207742586809
`targetAltHAE`	float	target altitude	309.8363786905352
`targetDistanceMeters`	float	distance to target	281.2324945266905
`predictedCE`	float	predicted error, meters	11.521343585384802
`TLE_Cat`	String	predicted error category	CAT_2
`elevationDataModel`	String	dataset that elevation data came from	Copernicus Global DSM 30m

POST /api/v1/openathena/location (Return detailed geolocation data of pixel within a drone image via provided metadata)

Parameters

name type data type description
none required JSON object JSON object containing image metadata

name	type	data type	description
`none`	required	JSON object	JSON object containing image metadata

POST Body JSON Object Key/Value Pairs

key name type data type description example
GPS Latitude required float latitude +- decimal degrees 33.837470333
GPS Longitude required float longitude +- decimal degrees -84.522598472
GPS Altitude semi-required float altitude in WGS84 Height Above Elipsoid (HAE) meters (see note above) 437.920107
MSL Altitude semi-required float altitude in Above Mean Sea Level (AMSL) meters according to EGM96 Geoid (see note above) 101.233
Focal Length required float focal length of image 6.72
Focal Length 35 optional float 35mm equivalent focal length 24.0
ImageWidth required int image width in pixels (scaled values are OK) 4032
ImageHeight required int image height in pixels (scaled vales are OK) 3024
Camera:Roll required float degrees roll of camera relative to ground (clockwise from camera perspective is positive) 0.0
GimbalPitchDegree required float degree pitch of gimbal or camera; measured in degrees downward from horizon 41.40
GimbalYawDegree required float compass heading in degrees; north is 0 and increasing clockwise 156.30
Camera Make required string manufacturer name of drone camera DJI
Camera Model required string model name of drone camera FC8482
Digital Zoom Ratio optional float digital zoom (centered crop) ratio, leave at 1.0 if digital crop has not been applied to image 1.0
timestamp_iso8601 optional string ISO8601 format time stamp YYYY-MM-DDTHH:mm:ss.sssZ 2026-01-25T21:28:43.123Z
xprop optional float x position of target within image frame as a proportion 0-1.0, measured from the left edge increasing rightward 0.50 is default
yprop optional float y position of target within image frame as a proportion 0-1.0, measured from the top edge increasing downwards 0.50 is default
dataset optional string Terrain elevation dataset to use for calculations, if possible COP30 (see list above)
drone camera intrinsics optional see above only needed if camera make and model not in database; see above for key names and descriptions
cottype optional string Type value to include CoT messages a-p-G (see COT specs)
cotuid optional string CoT UID to include in CoT messages OpenAthenaCore-November01-668
polarOrigin optional string Origin coordinates for use in calculating polar coordiantes of target (lat,lon or MGRS) 33.836739,-84.522274 or 16S GC 29277 46817
polarOriginAlt optional float Altitude in meters above MSL 242

key name	type	data type	description	example
`GPS Latitude`	required	float	latitude +- decimal degrees	33.837470333
`GPS Longitude`	required	float	longitude +- decimal degrees	-84.522598472
`GPS Altitude`	semi-required	float	altitude in WGS84 Height Above Elipsoid (HAE) meters (see note above)	437.920107
`MSL Altitude`	semi-required	float	altitude in Above Mean Sea Level (AMSL) meters according to EGM96 Geoid (see note above)	101.233
`Focal Length`	required	float	focal length of image	6.72
`Focal Length 35`	optional	float	35mm equivalent focal length	24.0
`ImageWidth`	required	int	image width in pixels (scaled values are OK)	4032
`ImageHeight`	required	int	image height in pixels (scaled vales are OK)	3024
`Camera:Roll`	required	float	degrees roll of camera relative to ground (clockwise from camera perspective is positive)	0.0
`GimbalPitchDegree`	required	float	degree pitch of gimbal or camera; measured in degrees downward from horizon	41.40
`GimbalYawDegree`	required	float	compass heading in degrees; north is 0 and increasing clockwise	156.30
`Camera Make`	required	string	manufacturer name of drone camera	DJI
`Camera Model`	required	string	model name of drone camera	FC8482
`Digital Zoom Ratio`	optional	float	digital zoom (centered crop) ratio, leave at 1.0 if digital crop has not been applied to image	1.0
`timestamp_iso8601`	optional	string	ISO8601 format time stamp YYYY-MM-DDTHH:mm:ss.sssZ	2026-01-25T21:28:43.123Z
`xprop`	optional	float	x position of target within image frame as a proportion 0-1.0, measured from the left edge increasing rightward	0.50 is default
`yprop`	optional	float	y position of target within image frame as a proportion 0-1.0, measured from the top edge increasing downwards	0.50 is default
`dataset`	optional	string	Terrain elevation dataset to use for calculations, if possible	COP30 (see list above)
`drone camera intrinsics`	optional	see above	only needed if camera make and model not in database; see above for key names and descriptions
`cottype`	optional	string	Type value to include CoT messages	a-p-G (see COT specs)
`cotuid`	optional	string	CoT UID to include in CoT messages	OpenAthenaCore-November01-668
`polarOrigin`	optional	string	Origin coordinates for use in calculating polar coordiantes of target (lat,lon or MGRS)	33.836739,-84.522274 or 16S GC 29277 46817
`polarOriginAlt`	optional	float	Altitude in meters above MSL	242

Responses

http code content-type response
200 application/json JSON object containing detailed geolocation information
400 application/json Location error

http code	content-type	response
`200`	`application/json`	JSON object containing detailed geolocation information
`400`	`application/json`	Location error

Returned JSON location Object Key/Value Pairs

key name data type description
targetLon float longitude decimal degrees
targetLat float latitude decimal degrees
targetDistanceMeters float distance to target in meters
targetAltHAE float target alt, height in meters above ellipsoid
targetAltEGM float target alt, meters EGM/Geoid/MSL
finalTheta float final target theta, degrees
linearError float estimate of linear error in meters
predictedCE float predicted circular error in meters
TLE_Cat string predicted circular error category
imageSelectedProportionY float target proportion in image, y-axis 0.0-1.0
imageSelectedProportionX float target proportion in image, x-axis 0.0-1.0
imageHeight float pixels
imageWidth float pixels
imageDateTimeUTC string UTC date/time image taken
pitchOffsetDegSelectedPoint float target pitch offset, degrees
finalAZ float final target azimuth, degrees
digitalZoomRatio float zoom factor
calculationDateTimeUTC string UTC date/time of calculation
azimuthOffsetUserCorrection float user azimuth correction, degrees
cameraRollAngleDeg float camera roll, degrees
isCameraModelRecognized boolean is drone camera in drone database
droneElevationHAE float drone alt in meters, height above ellipsoid
model string drone manufacturer
make string model
lensType string lens type perspective or fisheye
f_x float lens intrinsics
f_y float lens intrinsics
droneLatitude float decimal degrees
droneLongitude float longitude decimal degrees
cameraSlantAngleDeg float camera theta in degrees
yawOffsetDegSelectedPoint float target azimuth offset, degrees
imageFilename string image filename if present
focalLength float focal length for this image
targetUTM String target location in UTM coordinates
droneVerticalDatum String vertical datum drone reports altitude
terrainAltUnderDroneHAE float terrain alt in meters, height above ellipsoid
demFilename String filename of digital elevation model
elevationDataModel String dataset that elevation data came from
cotuid String if CoT was sent, message UID value
cottype String if CoT was sent, event type value
polarStatus String if polar coord requested, "OK" or error description
polarOrigin String if polar coord requested, polar origin
polarOriginAlt float if polar coord requested, polar origin alt (AMSL)
polarSlangRangeMeters float if polar coord requested, range from origin to target (meters)
polarElevationAngleDeg float if polar coord requested, elev angle (deg) from origin to target
polarElevationDelta float if polar coord requested, elev delta from origin to target (meters)
polarGridAzMrad float if polar coord requested, AZ in milliradians (0–≈6283 mrad)
polarGridAzMils6400 float if polar coord requested, AZ in NATO mils (0–6400) relative to grid north
polarGroundRangeMeters float if polar coord requested, ground range from origin to target (meters)

key name	data type	description
`targetLon`	float	longitude decimal degrees
`targetLat`	float	latitude decimal degrees
`targetDistanceMeters`	float	distance to target in meters
`targetAltHAE`	float	target alt, height in meters above ellipsoid
`targetAltEGM`	float	target alt, meters EGM/Geoid/MSL
`finalTheta`	float	final target theta, degrees
`linearError`	float	estimate of linear error in meters
`predictedCE`	float	predicted circular error in meters
`TLE_Cat`	string	predicted circular error category
`imageSelectedProportionY`	float	target proportion in image, y-axis 0.0-1.0
`imageSelectedProportionX`	float	target proportion in image, x-axis 0.0-1.0
`imageHeight`	float	pixels
`imageWidth`	float	pixels
`imageDateTimeUTC`	string	UTC date/time image taken
`pitchOffsetDegSelectedPoint`	float	target pitch offset, degrees
`finalAZ`	float	final target azimuth, degrees
`digitalZoomRatio`	float	zoom factor
`calculationDateTimeUTC`	string	UTC date/time of calculation
`azimuthOffsetUserCorrection`	float	user azimuth correction, degrees
`cameraRollAngleDeg`	float	camera roll, degrees
`isCameraModelRecognized`	boolean	is drone camera in drone database
`droneElevationHAE`	float	drone alt in meters, height above ellipsoid
`model`	string	drone manufacturer
`make`	string	model
`lensType`	string	lens type perspective or fisheye
`f_x`	float	lens intrinsics
`f_y`	float	lens intrinsics
`droneLatitude`	float	decimal degrees
`droneLongitude`	float	longitude decimal degrees
`cameraSlantAngleDeg`	float	camera theta in degrees
`yawOffsetDegSelectedPoint`	float	target azimuth offset, degrees
`imageFilename`	string	image filename if present
`focalLength`	float	focal length for this image
`targetUTM`	String	target location in UTM coordinates
`droneVerticalDatum`	String	vertical datum drone reports altitude
`terrainAltUnderDroneHAE`	float	terrain alt in meters, height above ellipsoid
`demFilename`	String	filename of digital elevation model
`elevationDataModel`	String	dataset that elevation data came from
`cotuid`	String	if CoT was sent, message UID value
`cottype`	String	if CoT was sent, event type value
`polarStatus`	String	if polar coord requested, "OK" or error description
`polarOrigin`	String	if polar coord requested, polar origin
`polarOriginAlt`	float	if polar coord requested, polar origin alt (AMSL)
`polarSlangRangeMeters`	float	if polar coord requested, range from origin to target (meters)
`polarElevationAngleDeg`	float	if polar coord requested, elev angle (deg) from origin to target
`polarElevationDelta`	float	if polar coord requested, elev delta from origin to target (meters)
`polarGridAzMrad`	float	if polar coord requested, AZ in milliradians (0–≈6283 mrad)
`polarGridAzMils6400`	float	if polar coord requested, AZ in NATO mils (0–6400) relative to grid north
`polarGroundRangeMeters`	float	if polar coord requested, ground range from origin to target (meters)

MISB Location Request

OpenAthena can also analyze drone telemetry directly from Motion Imagery Standards Board (MISB) format video metadata. OpenAthena maps the metadata from MISB into its internal format obviating the need to translate it syntactically and semantically. Supporting MISB telemetry, natively, makes integrating OpenAthena into a drone software pipeline much more straightforward.

For altitude, either Sensor Ellipsoid Height altitude (WGS84 height above ellipsoid or HAE in meters) or Sensor True Altitude (altitude above mean sea level or AMSL in meters) must be provided. HAE and AMSL are actually two different vertical datums which are deceptively similar, but can be off as much as 30 meters from each otrher in a typical case. Using one incorrectly for the other will add at least 20-30 meters of targeting error to OpenAthena's terrain-raycast.

In MISB metadata, the orientation of the drone or aircraft platform is separate from the relative orientation of the gimbal or sensor to the platform. Thus, OpenAthena performs a Euler angle composition to calculate the actual orientation of the camera before performing its terrain-raycast algorithm.

POST /api/v1/openathena/locationmisbsimple (Return simplified geolocation of pixel within a MISB drone image via provided metadata)

Parameters

name type data type description
none required JSON object JSON object containing image metadata

name	type	data type	description
`none`	required	JSON object	JSON object containing image metadata

POST Body JSON Object Key/Value Pairs

key name type data type description example
Sensor Latitude required float latitude +- decimal degrees 33.837470333
Sensor Longitude required float longitude +- decimal degrees -84.522598472
Sensor Ellipsoid Height semi-required float altitude in WGS84 Height Above Elipsoid (HAE) meters (see note above) 437.920107
Sensor True Altitude semi-required float altitude in Above Mean Sea Level (AMSL) meters according to EGM96 Geoid (see note above) 101.233
Sensor Relative Azimuth Angle required float relative rotation angle of sensor to platform longitudinal axis. Rotation angle between platform longitudinal axis and camera pointing direction as seen from above the platform. 10.0
Sensor Relative Elevation Angle required float Angle of sensor to platform longitudinal-transverse plane; negative angles down -5.0
Sensor Relative Roll Angle required float Relative roll angle of sensor to aircraft platform. Top of image is zero degrees. Positive angles are clockwise when looking from behind camera 5.0
Platform Heading Angle required float platform compass heading in degrees; north is 0 and increasing clockwise 156.30
Platform Pitch Angle required float platform pitch angle between longitudinal axis and horizontal plane; positive when platform nose is above horizontal plane 5.0
Platform Roll Angle required float platform angle between transverse axis and transvers-longitudinal plane. Positive angles for lowered right wing 0.0
Sensor Horizontal Field of View required float Sensor horizontal field of view 0..180 150.00
Sensor Vertical Field of View required float Sensor vertical field of view 0..180 55.0
Precision Time Stamp optional integer Unix epoch time (UTC) in microseconds since 1970-01-01T00:00:00Z 1773682200123456
xprop optional float x position of target within image frame as a proportion 0-1.0, measured from the left edge increasing rightward 0.50 is default
yprop optional float y position of target within image frame as a proportion 0-1.0, measured from the top edge increasing downwards 0.50 is default
dataset optional string Terrain elevation dataset to use for calculations, if possible COP30 (see list above)
cottype optional string Type value to include CoT messages a-p-G (see COT specs)
cotuid optional string CoT UID to include in CoT messages OpenAthenaCore-November01-668
polarOrigin optional string Origin coordinates for use in calculating polar coordiantes of target (lat,lon or MGRS) 33.836739,-84.522274 or 16S GC 29277 46817
polarOriginAlt optional float Altitude in meters above MSL 242

key name	type	data type	description	example
`Sensor Latitude`	required	float	latitude +- decimal degrees	33.837470333
`Sensor Longitude`	required	float	longitude +- decimal degrees	-84.522598472
`Sensor Ellipsoid Height`	semi-required	float	altitude in WGS84 Height Above Elipsoid (HAE) meters (see note above)	437.920107
`Sensor True Altitude`	semi-required	float	altitude in Above Mean Sea Level (AMSL) meters according to EGM96 Geoid (see note above)	101.233
`Sensor Relative Azimuth Angle`	required	float	relative rotation angle of sensor to platform longitudinal axis. Rotation angle between platform longitudinal axis and camera pointing direction as seen from above the platform.	10.0
`Sensor Relative Elevation Angle`	required	float	Angle of sensor to platform longitudinal-transverse plane; negative angles down	-5.0
`Sensor Relative Roll Angle`	required	float	Relative roll angle of sensor to aircraft platform. Top of image is zero degrees. Positive angles are clockwise when looking from behind camera	5.0
`Platform Heading Angle`	required	float	platform compass heading in degrees; north is 0 and increasing clockwise	156.30
`Platform Pitch Angle`	required	float	platform pitch angle between longitudinal axis and horizontal plane; positive when platform nose is above horizontal plane	5.0
`Platform Roll Angle`	required	float	platform angle between transverse axis and transvers-longitudinal plane. Positive angles for lowered right wing	0.0
`Sensor Horizontal Field of View`	required	float	Sensor horizontal field of view 0..180	150.00
`Sensor Vertical Field of View`	required	float	Sensor vertical field of view 0..180	55.0
`Precision Time Stamp`	optional	integer	Unix epoch time (UTC) in microseconds since 1970-01-01T00:00:00Z	1773682200123456
`xprop`	optional	float	x position of target within image frame as a proportion 0-1.0, measured from the left edge increasing rightward	0.50 is default
`yprop`	optional	float	y position of target within image frame as a proportion 0-1.0, measured from the top edge increasing downwards	0.50 is default
`dataset`	optional	string	Terrain elevation dataset to use for calculations, if possible	COP30 (see list above)
`cottype`	optional	string	Type value to include CoT messages	a-p-G (see COT specs)
`cotuid`	optional	string	CoT UID to include in CoT messages	OpenAthenaCore-November01-668
`polarOrigin`	optional	string	Origin coordinates for use in calculating polar coordiantes of target (lat,lon or MGRS)	33.836739,-84.522274 or 16S GC 29277 46817
`polarOriginAlt`	optional	float	Altitude in meters above MSL	242

Responses

http code content-type response
200 application/json JSON object containing detailed geolocation information
400 application/json Location error

http code	content-type	response
`200`	`application/json`	JSON object containing detailed geolocation information
`400`	`application/json`	Location error

Returned JSON location Object Key/Value Pairs

key name data type description example
targetLat float target latitude 33.8358084243378
targetLon float target longitude -84.5207742586809
targetAltHAE float target altitude 309.8363786905352
targetDistanceMeters float distance to target 281.2324945266905
predictedCE float predicted error, meters 11.521343585384802
TLE_Cat String predicted error category CAT_2
elevationDataModel String dataset that elevation data came from Copernicus Global DSM 30m

key name	data type	description	example
`targetLat`	float	target latitude	33.8358084243378
`targetLon`	float	target longitude	-84.5207742586809
`targetAltHAE`	float	target altitude	309.8363786905352
`targetDistanceMeters`	float	distance to target	281.2324945266905
`predictedCE`	float	predicted error, meters	11.521343585384802
`TLE_Cat`	String	predicted error category	CAT_2
`elevationDataModel`	String	dataset that elevation data came from	Copernicus Global DSM 30m

POST /api/v1/openathena/locationmisb (Return detailed geolocation of pixel within a MISB drone image via provided metadata)

Parameters

name type data type description
none required JSON object JSON object containing image metadata

name	type	data type	description
`none`	required	JSON object	JSON object containing image metadata

POST Body JSON Object Key/Value Pairs

key name type data type description example
Sensor Latitude required float latitude +- decimal degrees 33.837470333
Sensor Longitude required float longitude +- decimal degrees -84.522598472
Sensor Ellipsoid Height semi-required float altitude in WGS84 Height Above Elipsoid (HAE) meters (see note above) 437.920107
Sensor True Altitude semi-required float altitude in Above Mean Sea Level (AMSL) meters according to EGM96 Geoid (see note above) 101.233
Sensor Relative Azimuth Angle required float relative rotation angle of sensor to platform longitudinal axis. Rotation angle between platform longitudinal axis and camera pointing direction as seen from above the platform. 10.0
Sensor Relative Elevation Angle required float Angle of sensor to platform longitudinal-transverse plane; negative angles down -5.0
Sensor Relative Roll Angle required float Relative roll angle of sensor to aircraft platform. Top of image is zero degrees. Positive angles are clockwise when looking from behind camera 5.0
Platform Heading Angle required float platform compass heading in degrees; north is 0 and increasing clockwise 156.30
Platform Pitch Angle required float platform pitch angle between longitudinal axis and horizontal plane; positive when platform nose is above horizontal plane 5.0
Platform Roll Angle required float platform angle between transverse axis and transvers-longitudinal plane. Positive angles for lowered right wing 0.0
Sensor Horizontal Field of View required float Sensor horizontal field of view 0..180 150.00
Sensor Vertical Field of View required float Sensor vertical field of view 0..180 55.0
Precision Time Stamp optional integer Unix epoch time (UTC) in microseconds since 1970-01-01T00:00:00Z 1773682200123456
xprop optional float x position of target within image frame as a proportion 0-1.0, measured from the left edge increasing rightward 0.50 is default
yprop optional float y position of target within image frame as a proportion 0-1.0, measured from the top edge increasing downwards 0.50 is default
dataset optional string Terrain elevation dataset to use for calculations, if possible COP30 (see list above)
cottype optional string Type value to include CoT messages a-p-G (see COT specs)
cotuid optional string CoT UID to include in CoT messages OpenAthenaCore-November01-668
polarOrigin optional string Origin coordinates for use in calculating polar coordiantes of target (lat,lon or MGRS) 33.836739,-84.522274 or 16S GC 29277 46817
polarOriginAlt optional float Altitude in meters above MSL 242

key name	type	data type	description	example
`Sensor Latitude`	required	float	latitude +- decimal degrees	33.837470333
`Sensor Longitude`	required	float	longitude +- decimal degrees	-84.522598472
`Sensor Ellipsoid Height`	semi-required	float	altitude in WGS84 Height Above Elipsoid (HAE) meters (see note above)	437.920107
`Sensor True Altitude`	semi-required	float	altitude in Above Mean Sea Level (AMSL) meters according to EGM96 Geoid (see note above)	101.233
`Sensor Relative Azimuth Angle`	required	float	relative rotation angle of sensor to platform longitudinal axis. Rotation angle between platform longitudinal axis and camera pointing direction as seen from above the platform.	10.0
`Sensor Relative Elevation Angle`	required	float	Angle of sensor to platform longitudinal-transverse plane; negative angles down	-5.0
`Sensor Relative Roll Angle`	required	float	Relative roll angle of sensor to aircraft platform. Top of image is zero degrees. Positive angles are clockwise when looking from behind camera	5.0
`Platform Heading Angle`	required	float	platform compass heading in degrees; north is 0 and increasing clockwise	156.30
`Platform Pitch Angle`	required	float	platform pitch angle between longitudinal axis and horizontal plane; positive when platform nose is above horizontal plane	5.0
`Platform Roll Angle`	required	float	platform angle between transverse axis and transvers-longitudinal plane. Positive angles for lowered right wing	0.0
`Sensor Horizontal Field of View`	required	float	Sensor horizontal field of view 0..180	150.00
`Sensor Vertical Field of View`	required	float	Sensor vertical field of view 0..180	55.0
`Precision Time Stamp`	optional	integer	Unix epoch time (UTC) in microseconds since 1970-01-01T00:00:00Z	1773682200123456
`xprop`	optional	float	x position of target within image frame as a proportion 0-1.0, measured from the left edge increasing rightward	0.50 is default
`yprop`	optional	float	y position of target within image frame as a proportion 0-1.0, measured from the top edge increasing downwards	0.50 is default
`dataset`	optional	string	Terrain elevation dataset to use for calculations, if possible	COP30 (see list above)
`cottype`	optional	string	Type value to include CoT messages	a-p-G (see COT specs)
`cotuid`	optional	string	CoT UID to include in CoT messages	OpenAthenaCore-November01-668
`polarOrigin`	optional	string	Origin coordinates for use in calculating polar coordiantes of target (lat,lon or MGRS)	33.836739,-84.522274 or 16S GC 29277 46817
`polarOriginAlt`	optional	float	Altitude in meters above MSL	242

Responses

http code content-type response
200 application/json JSON object containing detailed geolocation information
400 application/json Location error

http code	content-type	response
`200`	`application/json`	JSON object containing detailed geolocation information
`400`	`application/json`	Location error

Returned JSON location Object Key/Value Pairs

key name data type description
targetLon float longitude decimal degrees
targetLat float latitude decimal degrees
targetDistanceMeters float distance to target in meters
targetAltHAE float target alt, height in meters above ellipsoid
targetAltEGM float target alt, meters EGM/Geoid/MSL
finalTheta float final target theta, degrees
linearError float estimate of linear error in meters
predictedCE float predicted circular error in meters
TLE_Cat string predicted circular error category
imageSelectedProportionY float target proportion in image, y-axis 0.0-1.0
imageSelectedProportionX float target proportion in image, x-axis 0.0-1.0
imageDateTimeUTC string UTC date/time image taken
pitchOffsetDegSelectedPoint float target pitch offset, degrees
finalAZ float final target azimuth, degrees
digitalZoomRatio float zoom factor
calculationDateTimeUTC string UTC date/time of calculation
azimuthOffsetUserCorrection float user azimuth correction, degrees
cameraRollAngleDeg float camera roll, degrees
droneElevationHAE float drone alt in meters, height above ellipsoid
droneLatitude float decimal degrees
droneLongitude float longitude decimal degrees
cameraSlantAngleDeg float camera theta in degrees
yawOffsetDegSelectedPoint float target azimuth offset, degrees
imageFilename string image filename if present
targetUTM String target location in UTM coordinates
droneVerticalDatum String vertical datum drone reports altitude
terrainAltUnderDroneHAE float terrain alt in meters, height above ellipsoid
demFilename String filename of digital elevation model
elevationDataModel String dataset that elevation data came from
cotuid String if CoT was sent, message UID value
cottype String if CoT was sent, event type value
polarStatus String if polar coord requested, "OK" or error description
polarOrigin String if polar coord requested, polar origin
polarOriginAlt float if polar coord requested, polar origin alt (AMSL)
polarSlangRangeMeters float if polar coord requested, range from origin to target (meters)
polarElevationAngleDeg float if polar coord requested, elev angle (deg) from origin to target
polarElevationDelta float if polar coord requested, elev delta from origin to target (meters)
polarGridAzMrad float if polar coord requested, AZ in milliradians (0–≈6283 mrad)
polarGridAzMils6400 float if polar coord requested, AZ in NATO mils (0–6400) relative to grid north
polarGroundRangeMeters float if polar coord requested, ground range from origin to target (meters)

key name	data type	description
`targetLon`	float	longitude decimal degrees
`targetLat`	float	latitude decimal degrees
`targetDistanceMeters`	float	distance to target in meters
`targetAltHAE`	float	target alt, height in meters above ellipsoid
`targetAltEGM`	float	target alt, meters EGM/Geoid/MSL
`finalTheta`	float	final target theta, degrees
`linearError`	float	estimate of linear error in meters
`predictedCE`	float	predicted circular error in meters
`TLE_Cat`	string	predicted circular error category
`imageSelectedProportionY`	float	target proportion in image, y-axis 0.0-1.0
`imageSelectedProportionX`	float	target proportion in image, x-axis 0.0-1.0
`imageDateTimeUTC`	string	UTC date/time image taken
`pitchOffsetDegSelectedPoint`	float	target pitch offset, degrees
`finalAZ`	float	final target azimuth, degrees
`digitalZoomRatio`	float	zoom factor
`calculationDateTimeUTC`	string	UTC date/time of calculation
`azimuthOffsetUserCorrection`	float	user azimuth correction, degrees
`cameraRollAngleDeg`	float	camera roll, degrees
`droneElevationHAE`	float	drone alt in meters, height above ellipsoid
`droneLatitude`	float	decimal degrees
`droneLongitude`	float	longitude decimal degrees
`cameraSlantAngleDeg`	float	camera theta in degrees
`yawOffsetDegSelectedPoint`	float	target azimuth offset, degrees
`imageFilename`	string	image filename if present
`targetUTM`	String	target location in UTM coordinates
`droneVerticalDatum`	String	vertical datum drone reports altitude
`terrainAltUnderDroneHAE`	float	terrain alt in meters, height above ellipsoid
`demFilename`	String	filename of digital elevation model
`elevationDataModel`	String	dataset that elevation data came from
`cotuid`	String	if CoT was sent, message UID value
`cottype`	String	if CoT was sent, event type value
`polarStatus`	String	if polar coord requested, "OK" or error description
`polarOrigin`	String	if polar coord requested, polar origin
`polarOriginAlt`	float	if polar coord requested, polar origin alt (AMSL)
`polarSlangRangeMeters`	float	if polar coord requested, range from origin to target (meters)
`polarElevationAngleDeg`	float	if polar coord requested, elev angle (deg) from origin to target
`polarElevationDelta`	float	if polar coord requested, elev delta from origin to target (meters)
`polarGridAzMrad`	float	if polar coord requested, AZ in milliradians (0–≈6283 mrad)
`polarGridAzMils6400`	float	if polar coord requested, AZ in NATO mils (0–6400) relative to grid north
`polarGroundRangeMeters`	float	if polar coord requested, ground range from origin to target (meters)

Miscellaneous

Show

GET /api/v1/openathena/up (Simple query to test if host is up and API key is valid)

Parameters

None

Responses

http code content-type response
http code content-type response
--------------- --------------------- -----------------------------------------------
200 application/json Server status; key is status
405 application/json Permission denied

http code	content-type	response
http code	content-type	response
---------------	---------------------	-----------------------------------------------
`200`	`application/json`	Server status; key is `status`
`405`	`application/json`	Permission denied

OpenAthena Core Administration

Show

Queries in this category require administration permissions be assigned to the API key you use. API keys are accessible via the apikeys APIs. CursorOnTarget messages can be sent to Team Awareness Kit (TAK) hosts which are configured via the takhosts APIs.

GET /api/v1/openathena/admin/status (Get the status of the server and container it is running within)

Parameters

None

Responses

http code content-type response
200 application/json Server status; key is status
405 application/json Permission denied

http code	content-type	response
`200`	`application/json`	Server status; key is `status`
`405`	`application/json`	Permission denied

GET /api/v1/openathena/admin/stats (Get server statistics and counters)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing stats and counters
405 application/json Permission denied

http code	content-type	response
`200`	`application/json`	JSON object containing stats and counters
`405`	`application/json`	Permission denied

POST /api/v1/openathena/admin/stats/reset (Reset server statistics and counters)

Parameters

None

Responses

http code content-type response
200 application/json N/A
405 application/json Permission denied

GET /api/v1/openathena/admin/config (Configuration parameters)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing configuration parameters
405 application/json Permission denied

GET /api/v1/openathena/admin/otapikey (Get the API key that Openathena Core uses for downloading DEMs from https://opentopography.org)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing OpenTopography API key; key is otapikey
405 application/json Permission denied

PUT /api/v1/openathena/admin/otapikey (Set the API key that OpenAthena Core uses for downloading DEMs from https://opentopography.org)

Parameters

None

PUT Body JSON Object Key/Value Pairs

key name type data type description example
otapikey required hex string New OpenTopography API key to use 123456789abcdefgh

Responses

http code content-type response
200 application/json JSON object containing result
405 application/json Permission denied

GET /api/v1/openathena/admin/apikeys (Get list of API keys that this server will accept.)

Parameters

None

Responses

http code content-type response
200 application/json JSON array of API keys that this server accepts; key is `apiKeys
405 application/json Permission denied

PUT /api/v1/openathena/admin/apikeys

(Modify an existing API key for use with this OpenAthena Core
server; modified key will be written to file.  The key itself cannot
be modified; only the entry fields can be)

Parameters

None

PUT Body JSON Object Key/Value Pairs

key name type data type description example
apikeystr required hex string Existing OA Core API key to reference 123456789abcdefgh
permission required string Permissions: 'admin' or 'user' user
organization required string Name of organization acme.com
contact required string Contact info coyote@acme.com

Responses

http code content-type response
200 application/json JSON object containing result; entry modified and written to file
405 application/json Permission denied

POST /api/v1/openathena/admin/apikeys (Create new API key for use with this OpenAthena Core server; new key will be written to file)

Parameters

None

POST Body JSON Object Key/Value Pairs

key name type data type description example
apikeystr required hex string New OA Core API key to use 123456789abcdefgh
permission required string Permissions: 'admin' or 'user' user
organization required string Name of organization acme.com
contact required string Contact info coyote@acme.com

Responses

http code content-type response
201 application/json JSON object containing result; new entry written to file
400 application/json Bad request; often invalid parameters
405 application/json Permission denied

DELETE /api/v1/openathena/admin/apikeys (Delete an existing API key from the OpenAthena Core key list)

Parameters

None

DELETE Body JSON Object Key/Value Pairs

key name type data type description example
apikeystr required hex string Existing OA Core API key to delete 123456789abcdefgh

Responses

http code content-type response
200 application/json JSONobject containing result; API key entry deleted and remaining keys written to file
404 application/json API key not found
405 application/json Permission denied

PUT /api/v1/openathena/admin/refreshdemcache (Force DEM cache refresh and return date/time of cache refresh)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing string date/time of cache refresh; key is demCacheDate
404 application/json Invalid DEM query

GET /api/v1/openathena/admin/defaultelevationdataset (Get the default elevation dataset Openathena Core will use when downloading DEMs from https://opentopography.org)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing default elevation dataset (see dataset valid values above); key is value
405 application/json Permission denied

PUT /api/v1/openathena/admin/defaultelevationdataset (Set the default elevation dataset OpenAthena Core will use when downloading DEMs from https://opentopography.org)

Parameters

None

PUT Body JSON Object Key/Value Pairs

key name type data type description example
value required string New default elevation dataset (see dataset valid values above) COP30

Responses

http code content-type response
200 application/json JSON object containing result
405 application/json Permission denied

GET /api/v1/openathena/admin/debug (Get the debug flag value)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing boolean value; key is value
405 application/json Permission denied

PUT /api/v1/openathena/admin/debug (Set debug flag value)

Parameters

None

PUT Body JSON Object Key/Value Pairs

key name type data type description example
value required boolean New debug flag value false

Responses

http code content-type response
200 application/json JSON object containing result
405 application/json Permission denied

GET /api/v1/openathena/admin/verbose (Get the verbose flag value)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing boolean value; key is value
405 application/json Permission denied

PUT /api/v1/openathena/admin/verbose (Set verbose flag value)

Parameters

None

PUT Body JSON Object Key/Value Pairs

key name type data type description example
value required boolean New verbose flag value false

Responses

http code content-type response
200 application/json JSON object containing result
405 application/json Permission denied

GET /api/v1/openathena/admin/autodemdownload (Get the flag indicating if OpenAthena Core should automatically download DEM data from OpenTopography.org)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing boolean value
405 application/json Permission denied

PUT /api/v1/openathena/admin/autodemdownload (Set flag indicating if OpenAthena Core should automatically download DEM data from OpenTopography.org)

Parameters

None

PUT Body JSON Object Key/Value Pairs

key name type data type description example
value required boolean New autodemdownload flag value true

Responses

http code content-type response
200 application/json JSON object containing result
405 application/json Permission Drone Imagesdenied

GET /api/v1/openathena/admin/sendcot (Get the flag indicating if OpenAthena Core should automatically send CursorOnTarget TAK messages)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing boolean value
405 application/json Permission denied

PUT /api/v1/openathena/admin/sendcot (Set flag indicating if OpenAthena Core should automatically send CursorOnTarget TAK messages)

Parameters

None

PUT Body JSON Object Key/Value Pairs

key name type data type description example
value required boolean New sendcot flag value true

Responses

http code content-type response
200 application/json JSON object containing result
405 application/json Permission denied

GET /api/v1/openathena/admin/demwidth (The default width and height, in meters, of digital elevation model data to download)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing int value
405 application/json Permission denied

PUT /api/v1/openathena/admin/demwidth (Set the default width and height, in meters, of digital elevation data to download)

Parameters

None

PUT Body JSON Object Key/Value Pairs

key name type data type description example
value required integer Width,height in meters 20000

Responses

http code content-type response
200 application/json JSON object containing result
405 application/json Permission denied

PUT /api/v1/openathena/admin/writeproperties (Write properties out to file specified via `-c` command-line option.)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing string date/time of write; key is propertiesDate
404 application/json Invalid query

PUT /api/v1/openathena/admin/writeapikeys (Write API keys out to file specified via `-k` command-line option.)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing string date/time of write; key is keysDate
404 application/json Invalid query

GET /api/v1/openathena/admin/takhosts (Get the list of TAK hosts that CursorOnTarget messages are sent to.)

Parameters

None

Responses

http code content-type response
200 application/json JSON array of TAK host entries; key is takhosts
405 application/json Permission denied

GET /api/v1/openathena/admin/takhosts/{key} (Get the TAK host, from the server's table of TAK hosts, with matching key.)

Parameters

name type data type description
{key} required string key value for the desired TAK host entry

Responses

GET /api/v1/openathena/admin/takhosts/count (Get the count of TAK hosts that this server sends CursorOnTarget messages to.)

Parameters

None

Responses

http code content-type response
200 application/json JSON object containing number of entries; key is count
404 application/json Invalid drone query

DELETE /api/v1/openathena/admin/takhosts (Delete this entry from the server's table of TAK hosts.)

Parameters

None

DELETE Body JSON Object Key/Value Pairs

key name type data type description example
cottakkey required string Key for TAK host entry to delete 4

Responses

http code content-type response
200 application/json JSONobject containing result
404 application/json TAKhost entry not found
405 application/json Permission denied

POST /api/v1/openathena/admin/takhosts (Create a new entry in this server's table of TAK hosts or update an existing entry.)

Parameters

None

POST Body JSON Object Key/Value Pairs

key name type data type description example
cottakkey required string Unique key to use for entry 4
cottakproto required udp local tcp
cottakhost required string Hostname or IP address argustak.com
cottakport required integer Protocol port number 8080
cottaksslclientkeystore required (cottakproto=ssl) string Filename of SSL client keystore cert.p12
cottaksslclientkeystorepassword required (cottakproto=ssl) string Password for client keystore changeit
cottaksslclientkeypassword required (cottakproto=ssl) string Password for client key changeme
cottakssltrustkeystore required (cottakproto=ssl) string Filename of SSL trust keystore tstore.p12
cottakssltrustkeystorepassword required (cottakproto=ssl) string Password for trust keystore changemetoo

Responses

http code content-type response
201 application/json JSONobject containing result; TAK host created
400 application/json Bad request due to invalid TAK host parameters

Examples

Show

Examples API calls using curl in bash or derivatives like zsh. (csh invocation requires backslashes to escape newline characters. ) Care must be taken with URLs and strings as shells differ on how to escape special characters like & and =.

DEM Cache Examples

List the entries in the DEM cache:

curl 'https://api.openathena.com/api/v1/openathena/dem?apikey=YOUR_API_KEY_HERE'

Download a DEM for a 15000 square meter area centered around GPS coordinates 33.829647,-84.518281

curl -X POST 'https://api.openathena.com/api/v1/openathena/dem?lat=33.829647&lon=-84.518281&len=15000&apikey=YOUR_API_KEY_HERE'

Search the Drone Info Database

Search for DJI FC2204 in the drone info database:

curl 'https://api.openathena.com/api/v1/openathena/drone?apikey=YOUR_API_KEY_HERE&search=djifc2204'

Search for Teal in the drone info database:

curl 'https://api.openathena.com/api/v1/openathena/drone?apikey=YOUR_API_KEY_HERE&search=teledyne'

Search for fisheye lens drones in the drone info database:

curl 'https://api.openathena.com/api/v1/openathena/drone/?search=fisheye&apikey=YOUR_API_KEY_HERE'

Get a count of the number of entries in the Drone database.

curl 'https://api.openathena.com/api/v1/openathena/drone/count?apikey=YOUR_API_KEY_HERE'

Geolocate Pixels in Drone Images

The example below for a locationsimple request resolves a location for a pixel in an image with the following metadata. The pixel location is proportionally specified as a proportion of the image (0-1.0,0-1.0) with the upper left corner being (0,0) and x increases rightwards while y increases downwards. For example, (0.5,0.5) is the image center and (1.0,1.0) is the bottom right corner. The image itself does not need to be uploaded -- merely the necessary metadata. The documentation as to the exact format of the metadata will be provided. It uses the simple location request that provides simplified geolocation data on return.

# basic locationsimple calc. request
curl -X POST 'https://api.openathena.com/api/v1/openathena/locationsimple?apikey=YOUR_API_KEY_HERE' -H "Content-Type: application/json" -d '
{"GPS Latitude" : "33.837470333333336",
"GPS Longitude" : "-84.52259847222223",
"Focal Length" : "6.72",
"ImageWidth" : "4032",
"ImageHeight" : "3024",
"Camera:Roll" : "0.0",
"Digital Zoom Ratio" : "1.0",
"GPS Altitude" : "437.920107",
"drone:GimbalPitchDegree" : "41.40",
"drone:GimbalYawDegree" : "156.30",
"tiff:Make" : "DJI",
"tiff:Model" : "FC8482",
"xprop" : "0.25",
"yprop" : "0.25",
}'

This query produces the following output

{
  "location": {
    "TLE_Cat": "CAT_2",
    "targetDistanceMeters": 538.4465179534826,
    "predictedCE": 11.312282733045901,
    "targetLon": -84.30760707719494,
    "targetAltHAE": 289.11412578910085,
    "elevationDataModel": "Copernicus Global DSM 30m",
    "targetLat": 33.87054790517167
  }
}

The example below is for a locationsimple calculation request using a specific DEM dataset. See dataset parameter values in section Analyzing Drone Images for a list of available datasets.

# LocationSimple with specific DEM dataset
curl -X POST 'https://api.openathena.com/api/v1/openathena/locationsimple?apikey=YOUR_API_KEY_HERE' -H "Content-Type: application/json" -d '
{"GPS Latitude" : "33.873739",
"GPS Longitude" : "-84.311059",
"Focal Length" : "6.72",
"ImageWidth" :  "4032",
"ImageHeight" : "3024",
"Camera:Roll" : "0.0",
"Digital Zoom Ratio" : "1.0",
"GPS Altitude" : "537.920107",
"drone:GimbalPitchDegree" : "41.40",
"drone:GimbalYawDegree" : "156.30",
"tiff:Make" : "DJI",
"tiff:Model" : "FC8482",
"xprop" : "0.25",
"yprop" : "0.25",
"dataset" : "3dep"
}'

The query produces the following output:

{
  "location": {
    "TLE_Cat": "CAT_2",
    "targetDistanceMeters": 547.4541272533297,
    "predictedCE": 11.312282733045901,
    "targetLon": -84.30754933250704,
    "targetAltHAE": 284.9516058069391,
    "elevationDataModel": "USGS 1/3 arc-second Digital Elevation Model 10m",
    "targetLat": 33.87049452266936
  }
}

The example below is for a locationsimple calculation request using custom camera intrinsics (camera calibration) values. This is useful for performing calculation requests for drone camera make+models with calibration values not yet in OpenAthena's droneModels.json database.

# locationsimple with a custom camera
curl -X POST 'https://api.openathena.com/api/v1/openathena/locationsimple?apikey=YOUR_API_KEY_HERE' -H "Content-Type: application/json" -d '
{"GPS Latitude" : "33.873739",
"GPS Longitude" : "-84.311059",
"Focal Length" : "6.72",
"ImageWidth" :  "4032",
"ImageHeight" : "3024",
"Camera:Roll" : "0.0",
"Digital Zoom Ratio" : "1.0",
"GPS Altitude" : "537.920107",
"drone:GimbalPitchDegree" : "41.40",
"drone:GimbalYawDegree" : "156.30",
"tiff:Make" : "CUSTOM",
"tiff:Model" : "DRONEMODEL",
"isThermal" : "false",
"widthPixels": "4032",
"heightPixels": "3024",
"ccdWidthMMPerPixel": "0.002225663181466/1.0",
"ccdHeightMMPerPixel": "0.002221383424304/1.0",
"lensType": "perspective",
"radialR1": "0.14007904012723732",
"radialR2": "-0.39797006527367595",
"radialR3": "0.4837999442176295",
"tangentialT1": "-0.0033106377888616196",
"tangentialT2": "0.002201030939220962",
"xprop" : "0.25",
"yprop" : "0.25"
}'

This query produces the following output

{
  "location": {
    "TLE_Cat": "CAT_2",
    "targetDistanceMeters": 538.4465179534826,
    "predictedCE": 11.312282733045901,
    "targetLon": -84.30760707719494,
    "targetAltHAE": 289.11412578910085,
    "elevationDataModel": "Copernicus Global DSM 30m",
    "targetLat": 33.87054790517167
  }
}

The example below for a location calcuation request resolves a location for a pixel in an image with the following metadata.

The pixel location is proportionally specified as a proportion of the image (0-1.0,0-1.0) with the upper left corner being (0,0) and x increases rightwards while y increases downwards. For example, (0.5,0.5) is the image center and (1.0,1.0) is the bottom right corner. The image itself does not need to be uploaded -- merely the necessary metadata. The location request provides additional, more verbose output compared to locationsimple

# location (verbose) request
curl -X POST 'https://api.openathena.com/api/v1/openathena/location?apikey=YOUR_API_KEY_HERE' -H "Content-Type: application/json" -d '
{"GPS Latitude" : "33.837470333333336",
"GPS Longitude" : "-84.52259847222223",
"Focal Length" : "6.72",
"Focal Length 35" : "24.0",
"ImageWidth" :	"4032",
"ImageHeight" :	"3024",
"Camera:Roll" :	"0.0",
"Digital Zoom Ratio" : "1.0",
"GPS Altitude" : "437.920107",
"drone:GimbalPitchDegree" : "41.40",
"drone:GimbalYawDegree" : "156.30",
"tiff:Make" : "DJI",
"tiff:Model" : "FC8482",
"xprop" : "0.25",
"yprop" : "0.25",
}'

This query produces the following output:

{
  "location": {
    "gimbalYawDegree": 156.3,
    "targetDistanceMeters": 281.2324945266905,
    "linearError": 5.9,
    "pitchOffsetDegSelectedPoint": 14.283329579602897,
    "imageDateTimeUTC": "2024-06-21T13:15:00Z",
    "imageSelectedProportionY": 0.25,
    "imageSelectedProportionX": 0.25,
    "targetCK42GKLat": 3748425.64455343,
    "targetAltHAE": 309.8363786905352,
    "finalAZ": 137.6430348057406,
    "digitalZoomRatio": 1,
    "calculationDateTimeUTC": "2024-09-03T00:46:46Z",
    "azimuthOffsetUserCorrection": 0,
    "slantRange": 281.2324945266905,
    "targetMGRS": "16SGC2941846715",
    "cameraRollAngleDeg": 0,
    "isCameraModelRecognized": "true",
    "droneElevationHAE": 437.920107,
    "droneLongitude": -84.52259847222223,
    "targetCK42Lon": -84.52088576188001,
    "targetLon": -84.5207742586809,
    "model": "fc8482",
    "make": "dji",
    "lensType": "perspective",
    "targetAltEGM": 279.16968582042205,
    "f_x": 3019.3246480906096,
    "imageWidth": 4032,
    "f_y": 3013.5185649268224,
    "targetCK42Lat": 33.83710905735875,
    "finalTheta": 27.1166704203971,
    "focalLength35": 24,
    "droneLatitude": 33.837470333333336,
    "targetLat": 33.8358084243378,
    "imageHeight": 3024,
    "cameraSlantAngleDeg": 41.4,
    "TLE_Cat": "CAT_2",
    "yawOffsetDegSelectedPoint": -18.656965194259424,
    "predictedCE": 11.521343585384802,
    "gimbalPitchDegree": 41.4,
    "targetCK42GKLon": 46729499.953724496,
    "targetUTM": "16 N 729418.1 3746715.77",
    "focalLength": 6.72
  }
}

The example below requests a location for a pixel in an image with MISB metadata. The pixel location is proportionally specified as a proportion of the image (0-1.0,0-1.0) with the upper left corner being (0,0) and x increases rightwards while y increases downwards. For example, (0.5,0.5) is the image center and (1.0,1.0) is the bottom right corner. The image itself does not need to be uploaded -- merely the necessary metadata.

# MISB location simple request
curl -X POST 'https://api.openathena.com/api/v1/openathena/locationmisbsimple?apikey=YOUR_API_KEY_HERE' -H 'Content-Type: application/json' -d '
{
    "Sensor Latitude": "33.8371893",
    "Sensor Longitude": "-84.5387701",
    "Sensor Ellipsoid Height": "386.3268577682946",
    "Sensor Relative Roll Angle": "0.0",
    "Sensor Relative Elevation Angle": "-36.0",
    "Sensor Relative Azimuth Angle": "0.0",
    "Platform Roll Angle": "0.0",
    "Platform Pitch Angle": "0.0",
    "Platform Heading Angle": "172.4",
    "Sensor Horizontal Field of View": "73.73979",
    "Sensor Vertical Field of View": "45.74733",
    "Precision Time Stamp": "1773682200123456",
    "xprop": "0.50",
    "yprop": "0.50"
}'

This query produces the following output:

{
  "location": {
    "TLE_Cat": "CAT_2",
    "targetDistanceMeters": 250.17114001752856,
    "predictedCE": 11.754449640455743,
    "targetLon": -84.53848052423864,
    "targetAltHAE": 239.3805446951789,
    "elevationDataModel": "USGS 3DEP 1/3 arc-second (10m) Digital Elevation Model",
    "targetLat": 33.83538660477129
  }
}

The same query as above but requesting more detailed geolocation information using locationmisb

# MISB location request, detailed response
curl -X POST 'https://api.openathena.com/api/v1/openathena/locationmisb?apikey=YOUR_API_KEY_HERE' -H 'Content-Type: application/json' -d '
{
    "Sensor Latitude": "33.8371893",
    "Sensor Longitude": "-84.5387701",
    "Sensor Ellipsoid Height": "386.3268577682946",
    "Sensor Relative Roll Angle": "0.0",
    "Sensor Relative Elevation Angle": "-36.0",
    "Sensor Relative Azimuth Angle": "0.0",
    "Platform Roll Angle": "0.0",
    "Platform Pitch Angle": "0.0",
    "Platform Heading Angle": "172.4",
    "Sensor Horizontal Field of View": "73.73979",
    "Sensor Vertical Field of View": "45.74733",
    "Precision Time Stamp": "1773682200123456",
    "xprop": "0.50",
    "yprop": "0.50"
}'

More detailed geolocation information returned is:


{
  "location": {
    "imageSelectedProportionY": 0.5,
    "imageSelectedProportionX": 0.5,
    "cotuid": "OpenAthenaCore-Romeo59-685",
    "targetAltHAE": 239.3805446951789,
    "finalAZ": 172.4,
    "targetAltEGM": 269.9817326060285,
    "hae": 239.3805446951789,
    "azimuthOffsetUserCorrection": 0,
    "targetMGRS": "16SGC2778046629",
    "droneLongitude": -84.5387701,
    "targetCK42Lon": -84.53859250521232,
    "targetLon": -84.53848052423864,
    "droneVerticalDatum": "WGS84",
    "EGM96Offset": -30.662308987663828,
    "targetAltEGM96": 270.04285368284275,
    "lat": 33.83538660477129,
    "imageFilename": "",
    "finalTheta": 36,
    "droneLatitude": 33.8371893,
    "targetLat": 33.83538660477129,
    "demFilename": "DEM_LatLon_33.750717_-84.549129_33.930566_-84.332597.3dep",
    "yawOffsetDegSelectedPoint": 0,
    "predictedCE": 11.754449640455743,
    "raySlantAngleDeg": 36,
    "EXIF DateTime": "2026:05:14 23:36:20",
    "targetUTM": "16 N 727780.36 3746629.62",
    "gimbalYawDegree": 172.4,
    "targetDistanceMeters": 250.17114001752856,
    "Processed DateTime": "2026-05-14T23:36:20Z",
    "gtype": "THREEDEP",
    "linearError": 5.9,
    "pitchOffsetDegSelectedPoint": 0,
    "imageDateTimeUTC": "2026-03-16T17:30:00.123456Z",
    "targetCK42GKLat": 3748339.4522445225,
    "lon": -84.53848052423864,
    "cottype": "a-p-G",
    "calculationDateTimeUTC": "2026-05-14T23:36:20Z",
    "geoidOffset": -30.601187910849603,
    "slantRange": 250.17114001752856,
    "cameraRollAngleDeg": 0,
    "droneElevationHAE": 386.3268577682946,
    "ce": 11.754449640455743,
    "targetCK42Lat": 33.83668723150278,
    "elevationDataModel": "USGS 3DEP 1/3 arc-second (10m) Digital Elevation Model",
    "cameraSlantAngleDeg": 36,
    "TLE_Cat": "CAT_2",
    "terrainAltHAE": 239.63392519858513,
    "terrainAltUnderDroneHAE": 245.40830025513623,
    "gimbalPitchDegree": 36,
    "dataset": "THREEDEP",
    "targetCK42GKLon": 46727861.513849184
  }
}

Manage Bulk DEM Downloads

Get a list of bulk DEM download jobs that have run or are currently running.

curl 'https://api.openathena.com/api/v1/openathena/bulkdemdownload?apikey=YOUR_API_KEY_HERE'

The test server has one bulk DEM downloader currently running. The query returns:

{
  "bulkdemdownloadqueue": [
    {
      "lat1": 34.587131,
      "lat2": 34.770985,
      "queuePosition": 0,
      "numberTiles": 15,
      "created": "Thu May 07 15:55:31 EDT 2026",
      "centerLon": -98.520264,
      "length": 15000,
      "started": "Thu May 07 15:55:31 EDT 2026",
      "finished": "n/a",
      "numberDownloads": 0,
      "crossesDateLine": false,
      "overlap": 0.1,
      "lon1": -98.784119,
      "lon2": -98.256409,
      "numberDownloadErrors": 0,
      "id": "78e3b6b1-c26a-45b2-b6f4-fc3f8c570aa5",
      "centerLat": 34.679058,
      "dataset": "COP30",
      "jobname": "Test Download",
      "status": "RUNNING"
    }
  ]
}

If the above referenced bulk DEM download job was running, and we wanted to stop it, we would use this command with the above job's ID value:

curl -X POST 'https://api.openathena.com/api/v1/openathena/bulkdemdownload/78e3b6b1-c26a-45b2-b6f4-fc3f8c570aa5/stop?apikey=YOUR_API_KEY_HERE'

The following result is returned.

{"result":"OK"}

Lets say we wanted to create a bulk DEM downloader for an area in the rectangle defined by these two lat,lon opposite corners: 34.587130635326986,-98.78411860205233 and 34.770985248227944,-98.2564087305218 We specify tiles should be 20,000 meters square with an overlap of 15 percent. Further, we specify the USGS 3DEP elevation dataset.

curl -X POST 'https://api.openathena.com/api/v1/openathena/bulkdemdownload?apikey=YOUR_API_KEY_HERE' -H 'Content-Type: application/json' -d '
{
  "lat1": "34.587130635326986",
  "lon1": "-98.78411860205233",
  "lat2": "34.770985248227944",
  "lon2": "-98.2564087305218",
  "len": "20000",
  "overlap": "0.15",
  "jobname" "test bulk",
  "dataset": "3dep"
}'

That command produces the following result:

{
  "result": "ok",
  "bulkdemdownloader": {
    "lat1": 34.587131,
    "lat2": 34.770985,
    "queuePosition": -1,
    "numberTiles": 15,
    "created": "Thu May 07 16:17:31 EDT 2026",
    "centerLon": -98.520264,
    "length": 20000,
    "started": "n/a",
    "finished": "n/a",
    "numberDownloads": 0,
    "crossesDateLine": false,
    "overlap": 0.15,
    "lon1": -98.784119,
    "lon2": -98.256409,
    "numberDownloadErrors": 0,
    "id": "7ecbf118-35e3-4f92-a779-8101546009fd",
    "centerLat": 34.679058,
    "dataset": "3DEP",
    "jobname": "test bulk",
    "status": "CREATED"
  }
}

Legal

Show

Unless stipulated otherwise by express written agreement with Theta Informatics LLC:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Target Location Error output is only an estimate and may not be certified by relevant authorities. Target Location Error estimation values have been calibrated from real world test data for some drone models.

https://theta.limited

CAGE: 9Q433

SAM.gov UEI: KZ7PCDTMVRD5

DUNS#: 129898542

http code	content-type	response
`200`	`application/json`	JSON object containing configuration parameters
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSON object containing OpenTopography API key; key is `otapikey`
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSON object containing `result`
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSON array of API keys that this server accepts; key is `apiKeys
`405`	`application/json`	Permission denied

key name	type	data type	description	example
`apikeystr`	required	hex string	Existing OA Core API key to reference	123456789abcdefgh
`permission`	required	string	Permissions: 'admin' or 'user'	user
`organization`	required	string	Name of organization	acme.com
`contact`	required	string	Contact info	coyote@acme.com

http code	content-type	response
`200`	`application/json`	JSON object containing `result`; entry modified and written to file
`405`	`application/json`	Permission denied

http code	content-type	response
`201`	`application/json`	JSON object containing `result`; new entry written to file
`400`	`application/json`	Bad request; often invalid parameters
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSONobject containing `result`; API key entry deleted and remaining keys written to file
`404`	`application/json`	API key not found
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSON object containing default elevation dataset (see `dataset` valid values above); key is `value`
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSON object containing boolean value; key is `value`
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSON object containing boolean `value`
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSON object containing int `value`
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSON array of TAK host entries; key is `takhosts`
`405`	`application/json`	Permission denied

http code	content-type	response
`200`	`application/json`	JSONobject containing `result`
`404`	`application/json`	TAKhost entry not found
`405`	`application/json`	Permission denied

key name	type	data type	description	example
`cottakkey`	required	string	Unique key to use for entry	4
`cottakproto`	required	udp	local	tcp
`cottakhost`	required	string	Hostname or IP address	argustak.com
`cottakport`	required	integer	Protocol port number	8080
`cottaksslclientkeystore`	required (cottakproto=ssl)	string	Filename of SSL client keystore	cert.p12
`cottaksslclientkeystorepassword`	required (cottakproto=ssl)	string	Password for client keystore	changeit
`cottaksslclientkeypassword`	required (cottakproto=ssl)	string	Password for client key	changeme
`cottakssltrustkeystore`	required (cottakproto=ssl)	string	Filename of SSL trust keystore	tstore.p12
`cottakssltrustkeystorepassword`	required (cottakproto=ssl)	string	Password for trust keystore	changemetoo

http code	content-type	response
`201`	`application/json`	JSONobject containing `result`; TAK host created
`400`	`application/json`	Bad request due to invalid TAK host parameters