API Endpoints

Endpoint	Purpose	Required	Optional
/api/v1/elevation/point	Get elevation at a single point	key,via	crs,dataset
/api/v1/elevation/points	Get elevation as multiple points	key,via	crs,dataset
/api/v1/sources	Get information about the available dataset at a single point	key,via	none

URL Formatting

To use this API it is a prerequisite that your URLs are properly formatted. Demapi can make no guarantees on whether malformed query will successfully run. In fact, more often than not, malformed queries will fail.

The following characters are used when formatting: ?, &

To indicate to API that you are starting your query append the ? after endpoint. Add a a query parameter. Each additional parameter is append to the URL with &.

A correctly formatted URL will look something like this:

https://{domain}{endpoint}?{first_parameter}&{second_parameter}&...

Where the domain is replaced with demapi.com, and endpoint is replaced with a given endpoint from the table above, as the /api/v1/elevation/point. This will yield:

https://demapi.com/api/v1/elevation/point?{first_parameter}&{second_parameter}&...

Next the parameters must be replaced.

Query Parameters

A query parameter is composed of two elements the parameter (or option) itself and a value. These are provided by the user to specify the actions to be taken by the API call. Correct formatting looks like:

{option}={value}

Which is to say that options set to a value as per the user's preference. When an API call is made all options passed in the URL are checked. The server then processes the options' values to yield an appropriate response.

There are only several options per endpoint, wome are required, while others are optional.

Available Query Parameters

key — The key option, also referred to as the API key, is your unique identifier for accessing and using the API. Whenever making a query you must provide your key somewhere in the query URL.

key={your_api_key}

When first creating your account, you must generate a key. A newly generated key looks something like: yTnaPMi.68tqUHHAqw68XJs2Lzapgxn2Ogubi52E (note: this is non-function key for this example). The key is made up of 2 parts: a key identifier, which is the first 7 characters before the . and the actual secret key, which is the 32 characters after the dot. When generating a key, the secret portion will only be displayed once. The identifier is visible at all times from your personal API keys page. It is used help you reconize previously created keys. Nevertheless, once a key has been created you must save your key to a secure place, accessible to you for when you wish to use the API. For security reasons, if you lose your key it cannot be retrieved and you must generate a new key to use.

via — Via is the query tag used for providing the API with a location from which to retrieve an elevation.

Via is made up of an X and Y coordinate when using non-spherical coordinates (projected coordinates). And used a longitude and latitude coordinate when using spherical coordinates (such as GPS).

Any coordinate can be entered into the API, however, results will only be returned for coordinates for which data or datasets are available.

Each coordinate is separated by a comma ,

The dot . is used as standard for decimal denoted coordinates.

Endpoint /api/v1/elevation/point accepts only 1 coordinate pair. While a endpoint /api/v1/elevation/points accepts up to 500 points separated by the vertical line symbol |

/api/v1/elevation/point via={x},{y} OR via={lon},{lat}

or

/api/v1/elevation/points via={x},{y}|{x},{y}|... OR via={lon},{lat}|{lon},{lat}|...

crs — CRS stands for coordinate reference system. Not all DEMs are the same, some use different coordinate systems. Demapi will try to smartly convert between CRSs. However it is often most accurate to use the native CRS of the DEM. For example, normal GPS coordinates are provided in a system called WGS84, while the DEM for a country like the Netherland is provided in a local coordinate system called “Rijksdriehoekstelsel” (RD). In that regard, may be necessary to specify the type of coordinates your are using in your query.

Demapi assumes the locations local coordinate system is used. In order to use GPS (WGS84) coordinates, this needs to be specified with the CRS tag as:

crs=wgs84

This is done, because querying the dataset’s native coordinate system provides results closest to the original raw data. While using a non-native coordinate system requires conversion, which can cause small discrepancies in the final result.

Example API Call - Sources

Example API Call - Points

Example API Call using Python