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 inquiries@theta.limited

OpenAthena API Summary:

Examining and Using the Digital Elevation Model Cache

Show
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}[&gtype={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
gtype 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
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 OpenAthenaCore 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.

OpenAthenaCore analyzes drone image metadata using elevation data automatically downloaded from OpenTopography.org. By default, OpenAthenaCore downloads data from the COP30 digital surface model dataset. Other datasets are now supported if your OpenTopography subscription level provides access to them. To specify a different elevation dataset, set and pass the gtype parameter in your location API calls. (gtype is short for GeoTiffDataSetType.)

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 OpenAthenaCore internal, 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
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 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 41.40
drone:GimbalYawDegree required float compass heading in degrees 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)
drone camera intrinsics optional see above see above for key, type, description
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 41.40
drone:GimbalYawDegree required float compass heading in degrees 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)
drone camera intrinsics optional see above see above for key, type, description
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 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
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 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 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.E.g. (0.5,0.5) would be the center of the image and (1.0,1.0) would be 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.

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": 281.2324945266905,
    "predictedCE": 11.521343585384802,
    "targetLon": -84.5207742586809,
    "targetAltHAE": 309.8363786905352,
    "targetLat": 33.8358084243378
  }
}

The example below 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. E.g. (0.5,0.5) would be the center of the image and (1.0,1.0) would be the bottom right corner. The image itself does not need to be uploaded -- merely the necessary metadata.

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