Elevation API

What is the Elevation API?

The Elevation API takes a given set of coordinates (latitude and longitude) and returns the elevation details for that location. You can provide coordinates and get elevation information in return. This includes both Elevation of Land as well as Depth of Seas. GeoCat only uses high-quality Goverment and Commercial data for this process, so you can be assured of extemely high levels of accuracy.

1) Accessing the API

For individual requests, we have a REST API endpoint. For bulk requests, you can upload a file in your Client Area account. This documentation is in reference to the HTTP REST API Endpoint. Please note: This API endpoint REQUIRES an API Key. You can find your API Key in the Client Area.

The API is available at the following endpoint: https://api.geocat.com/v3/elevation/

2) Request Parameters

The API only accepts 3 parameters in GET format:

lat = the latitude of the requested location
lon = the longitude of the requested location
key = your API Keys from the Client Area

*All parameters are REQUIRED *

3) Return Format

The API returns data in a clean, "pretty print", jSON format. This format is both Human and Computer readable. You can for example test the API in a web browser and will be able to read the output without special softare. You could also incorporate it into software using "jSON decoding" or equivalent in your programming language. We actually recommend testing your query in your browser first to ensure that you get the expected results before incorporating the results into your software or program to ensure you have the proper format and to see the expected output.

4) Example Return Data

An Example of the jSON return is as follows:

{
    "copyright": {
        "notice": "All data provided is property of GeoCat.com. Usage is subject to the Terms of Service and Privacy Policy.",
        "terms_of_service": "https:\/\/www.geocat.com\/terms-of-service\/",
        "privacy_policy": "https:\/\/www.geocat.com\/privacy-policy\/"
    },
    "status": {
        "request": {
            "key": "VALID",
            "latitude": "VALID",
            "longitude": "VALID"
        },
        "account": {
            "userid": "248354",
            "key": "0a1e1dd1-a920-11ef-9431-00163e25de56",
            "status": "ACTIVE",
            "plan": "UNLIMITED",
            "free_used": 2500,
            "free_left": 0,
            "paid_used": 438,
            "paid_left": 0,
            "expires": "2025-12-22 22:20:54"
        },
        "query": {
            "type": "PAID",
            "allow": true,
            "allow_reason": "UNLIMITED_ACCOUNT",
            "method": "ELEVATION",
            "requested": "27.988100,86.925000",
            "found": true,
            "time_taken": "205ms"
        }
    },
    "result": {
        "meters": 8627,
        "yards": 9435,
        "feet": 28304,
        "fathoms": 4717
    }
}

5) The "status" section

Here is an example of the status section:

    "status": {
        "request": {
            "key": "VALID",
            "latitude": "VALID",
            "longitude": "VALID"
        },
        "account": {
            "userid": "248354",
            "key": "0a1e1dd1-a920-11ef-9431-00163e25de56",
            "status": "ACTIVE",
            "plan": "UNLIMITED",
            "free_used": 2500,
            "free_left": 0,
            "paid_used": 438,
            "paid_left": 0,
            "expires": "2025-12-22 22:20:54"
        },
        "query": {
            "type": "PAID",
            "allow": true,
            "allow_reason": "UNLIMITED_ACCOUNT",
            "method": "ELEVATION",
            "requested": "27.988100,86.925000",
            "found": true,
            "time_taken": "205ms"
        }
    },

The status section contains the sub-sections as described here:

request = Contains info on the request validation This sub-section will ALWAYS be returned, regardless of given parameters. Contains the following fields:
key = Contains the validation status of the provided API key. May contains the following values:
- VALID = The API key was provided, it was validated, and exists in the system.
- INVALID = The API key was provided, but is not in a valid format or was not found in the system.
- MISSING = The API key was not provided. Check that the "key" parameter is provided to the API.
latitude = Contains the validation status of the provided latitude. May contains the following values:
- VALID = The latitude was provided, it was validated, and is correct format.
- INVALID = The latitude was provided, but is not in a valid format.
- MISSING = The latitude was not provided. Check that the "lat" parameter is provided to the API.
longitude = Contains the validation status of the provided longitude. May contains the following values:
- VALID = The longitude was provided, it was validated, and is correct format.
- INVALID = The longitude was provided, but is not in a valid format.
- MISSING = The longitude was not provided. Check that the "lon" parameter is provided to the API.
account = This sub-section is only returned if the request->key field is "VALID". Contains the following fields:
userid = Your user ID number in the system. Not really usefuly for users, but may be requested by support for troubleshooting.
key = Your API key. Should match the key provided in your request.
status = The status of your account at GeoCat. May contains the following values:
- ACTIVE = Your account is fully activated and can be used to access the API.
- INACTIVE = Your account has not been activate. You need to verify your email address to activate your account.
- TERMINATED = Your account was closed or terminated. If you wish to reactivate your account, you'll need to contact support.
plan = Tells you which plan you are currently using. May contains the following values:
- FREE_TIER = You do not have an active paid plan. You are limited to 2500 queries daily any anything over this will use from your credit balance, should you have one.
- SMALL_TIER = You are on a SMALL plan. This plan includes 25,000 PAID queries daily above the 2500 free limit (27,500 queries total)
- MEDIUM_TIER = You are on a SMALL plan. This plan includes 50,000 PAID queries daily above the 2500 free limit (52,500 queries total)
- LARGE_TIER = You are on a SMALL plan. This plan includes 75,000 PAID queries daily above the 2500 free limit (77,500 queries total)
- UNLIMITED = You are on an Unlimited Plan. This plan is our largest tier possible and allows for limitless usage of the API while the package is active.
free_used = How much of your free limit has been used today. Max is 2500.
free_left = How much of your free limit is remaining for today. Max is 2500.
paid_used = How much of your paid credits have been used today over the 2500 free limit.
paid_left = How much of your paid credits is remaining: If on FREE_TIER, this will be the amount of paid credit you have left. If you are on a monthly plan, this will be the remaining limit for today. If you are on an UNLIMITED plan, this will show 0 but all queries will be allowed.
expires = The expiration date of your current plan. After this date, your account will be reverted to "FREE_TIER" unless you renew it. If on the FREE_TIER, this will return "NEVER", as Free Tier accounts do not have an expiration date.
query = This sub-section is only returned if all fields in the request section are "VALID" and account status is "ACTIVE". Contains the following fields:
type = The query type. May contains the following values:
- FREE = Your account is below the free limit and this query is using from your free limit.
- PAID = You are over the free limit and this query is using credit or your plan.
allow = Whether or not this query was allowed to be processed. May contains the following values:
- true = This query was allowed to proceed. Check "found" field to check if results were found.
- false = This query was not allowed to proceed. Please check "allow_reason" field.
allow_reason = Why the "allow" field is true or false. May contains the following values:
- UNDER_FREE_LIMIT = Allowed because you are below the daily free limit.
- UNDER_PAID_LIMIT = Allowed because you had credit or an active paid plan.
- UNLIMITED_ACCOUNT = Allowed because you are on an Unlimited Plan.
- OVER_LIMIT = Was NOT allowed because you are over free limit, do not have an active plan, and have no credits.
method = Should always return "ELEVATION".
requested = Validated requested lat+lon in format "lat,lon". May not match exactly your input if it required correction to be processed. For example, if you provided more than 6 digits after the decimal place, they will have been trunicated here. If you provided less than 6 digits after the decimal point, it will have been padded with trailing zeros here.
found = Whether or not a result was found for the given query. May contains the following values:
- true = A result was found. There will be a result section returned.
- false = A result was not found. There will NOT be a result section returned.
time_taken = The amount of time, in milliseconds, that our system took to process your query. Will be numeric with a trailing "ms" for example "8ms".

6) The "result" section

Here is an example of the result section:

    "result": {
        "meters": 8627,
        "yards": 9435,
        "feet": 28304,
        "fathoms": 4717
    }

The result section WILL contain the following fields:

meters = Will contain the elevation in meters. Values my be positive or negative.
yards = Will contain the elevation in yards. Values my be positive or negative.
feet = Will contain the elevation in feet. Values my be positive or negative.
fathoms = Will contain the elevation in fathoms. Values my be positive or negative.

BACK TO HOMEPAGE