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 any single drone image. It does this by combining drone position and orientation data with a digital twin of terrain elevation.

OpenAthena obtains precise ground coordinates (median error < 10 meters) for any single drone image pixel, without the need for any special hardware. This is extremely useful for use of drones for search and rescue, public safety, defense technology, and more.

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

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

OpenAthena API Summary:

Examining and Using the Digital Elevation Model Cache

Show

OpenAthena analyzes drone image metadata using elevation data automatically downloaded from OpenTopography.org. By default, OpenAthena downloads data from the USGS 3DEP digital terrain model dataset for areas in the U.S. and Canada and the global COP30 digital surface model dataset elsewhere. Once downloaded, the elevation data, or DEMs, are stored in the server's demcache directory and are cached in memory for faster access and response times.

Other datasets are now supported if your OpenTopography subscription level provides access to them. To specify a different elevation dataset, set and pass the dataset (or gtype) parameter, where appropriate, in API. (gtype is short for GeoTiffDataSetType. This type may also be referred to, in query parameters, as dataset.)

gtype 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)
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
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
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
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
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
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
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`
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
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
Responses
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={gtype}] (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 gtype Optional elevation dataset (see gtype above)
Responses
http code content-type response
200 application/json JSON object containing altitude info; the fields are terrainAltWGS84 terrainAltAMSL
terrainEGM96Offset demDescription
400 application/json Invalid inputs, no matching DEM, etc.

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)
Responses
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
Responses
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
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

Analyzing Drone Images

Show

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

For altitude, either GPS altitude (HAE) in meters or MSL altitude in meters must be provided.

OpenAthena analyzes drone image metadata using elevation data automatically downloaded from OpenTopography.org. By default, OpenAthena downloads data from the USGS 3DEP digital terrain model dataset for areas in the U.S. and Canada and the global COP30 digital surface model dataset elsewhere. Once downloaded, the elevation data, or DEMs, are stored in the server's demcache directory and are cached in memory for faster access and response times.

Other datasets are now supported if your OpenTopography subscription level provides access to them. To specify a different elevation dataset, set and pass the dataset (or gtype) parameter, where appropriate, in API. (gtype is short for GeoTiffDataSetType. This type may also be referred to, in query parameters, as dataset.)

gtype 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)

OpenAthenaCore bundles a database of known drones/cameras and references that database for camera intrinsics using the drone make and model included in the image metadata. Callers can optionally include drone camera intrinsics parameters. Those optional parameters or intrinsics are documented below.

optional drone camera intrinsics
key name data type description example
isThermal boolean true if thermal camera; false otherwise default false
widthPixels int pixel width of full resolution camera image 5472
heightPixels int pixel height of full resolution camera image 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
POST Body JSON Object Key/Value Pairs
key name type data type description example
Name optional string Unique string for cache lookup example42.jpg
GPS Latitude required float latitude +- decimal degrees 33.837470333
GPS Longitude required float longitude +- decimal degrees -84.522598472
Focal Length required float focal length of image 6.72
Focal Length 35 optional float 35mm equivalent focal length 24.0
ImageWidth required int width in pixels of image 4032
ImageHeight required int height in pixels 3024
Camera:Roll required float camera roll in degrees (positive is clockwise from the camera's perspective) 0.0
Digital Zoom Ratio required float zoom ratio 1.0
GPS Altitude semi-required float altitude in WGS84 HAE meters (see note above) 437.920107
MSL Altitude semi-required float altitude in MSL meters (see note above) 101.233
drone:GimbalPitchDegree required float degree pitch of gimbal or camera (measured in degrees downward from the horizon) 41.40
drone:GimbalYawDegree required float compass heading in degrees (measured North is 0 and increasing clockwise) 156.30
tiff:Make required string make of drone DJI
tiff:Model required string drone model FC8482
Date/Time Original optional string YYYY:MM:DD HH:MM:SS 2024:06:21 09:15:00
xprop optional float image coordinates as a proportion 0-1.0, measured from the top left increasing rightwards and downwards 0.50 is default
yprop optional float image coordinates as a proportion 0-1.0, measured from the top left increasing rightwards and downwards 0.50 is default
maritimemode deprecated boolean Set for calculations over oceans false
gtype optional gtype Elev dataset to use if possible COP30 (see list above)
dataset optional gtype Elev dataset to use if possible COP30 (see list above)
drone camera intrinsics optional see above see above for key, type, description
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
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
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
POST Body JSON Object Key/Value Pairs
key name type data type description example
Name optional string Unique string for cache lookup example42.jpg
GPS Latitude required float latitude +- decimal degrees 33.837470333
GPS Longitude required float longitude +- decimal degrees -84.522598472
Focal Length required float focal length of image 6.72
Focal Length 35 optional float 35mm equivalent focal length 24.0
ImageWidth required int width in pixels of image 4032
ImageHeight required int height in pixels 3024
Camera:Roll required float degrees 0.0
Digital Zoom Ratio required float zoom ratio 1.0
GPS Altitude semi-required float altitude in WGS84 HAE meters (see note above) 437.920107
MSL Altitude semi-required float altitude in MSL meters (see note above) 101.233
drone:GimbalPitchDegree required float degree pitch of gimbal or camera (measured in degrees downward from the horizon) 41.40
drone:GimbalYawDegree required float compass heading in degrees (measured North is 0 and increasing clockwise) 156.30
tiff:Make required string make of drone DJI
tiff:Model required string drone model FC8482
Date/Time Original optional string YYYY:MM:DD HH:MM:SS 2024:06:21 09:15:00
xprop optional float image coordinates as a proportion 0-1.0, measured from the top left increasing rightwards and downwards 0.50 is default
yprop optional float image coordinates as a proportion 0-1.0, measured from the top left increasing rightwards and downwards 0.50 is default
maritimemode deprecated boolean Set for calculations over oceans false
gtype optional gtype Elev dataset to use if possible COP30 (see list above)
dataset optional gtype Elev dataset to use if possible COP30 (see list above)
drone camera intrinsics optional see above see above for key, type, description
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 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
targetAltEGM96 float target alt, meters EGM96/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 pitch angle offset for selected pixel within the image frame (positive is downwards)
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 in degrees (positive is clockwise from the camera's perspective)
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 yaw angle offset for selected pixel within the image frame (positive is rightwards)
filename 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

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

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 =.

Get a list of the DEM cache entries:

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

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'

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'

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 gtype 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 '
{"Name": "uniquename",
"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",
"gtype" : "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 '
{"Name": "uniquename",
"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 '
{"Name": "uniquename",
"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",
"Date/Time Original" : "2024:06:21 09:15:00",
"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",
    "targetAltEGM96": 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
  }
}



© 2025 Theta Informatics LLC

https://theta.limited

CAGE: 9Q433

SAM.gov UEI: KZ7PCDTMVRD5

DUNS#: 129898542