Reverse Geocoding

What is Reverse Geocoding?

Reverse Geocoding is the process of taking a given set of coordinates (latitude and longitude) and converting them into a physical location name such as Address, Postcode, Administrative Division, etc. With the GeoCat Reverse Geocoding API, you can provide coordinates and get full address or location data in return. GeoCat only uses high-quality Goverment and Commercial data for this process, so you can be assured of extremely 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/reverse/

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 software. 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": 316,
            "paid_left": 0,
            "expires": "2025-12-22 22:20:54"
        },
        "query": {
            "type": "PAID",
            "allow": true,
            "allow_reason": "UNLIMITED_ACCOUNT",
            "method": "REVERSE",
            "requested": "-42.896346,147.322658",
            "found": true,
            "time_taken": "79ms"
        }
    },
    "result": {
        "id": "210708",
        "match_type": "ADDRESS_LEVEL",
        "full_address": "50 Regent St, Sandy Bay, TAS 7005, Australia",
        "house_number": "50",
        "street_name": "Regent St",
        "street_full": "50 Regent St",
        "postcode": "7005",
        "admin3_name": "Sandy Bay",
        "admin3_type": "Locality",
        "admin2_name": "Hobart",
        "admin2_type": "City",
        "admin1_short": "TAS",
        "admin1_long": "Tasmania",
        "admin1_type": "State",
        "country_alpha2": "AU",
        "country_alpha3": "AUS",
        "country_short": "Australia",
        "country_long": "Commonwealth of Australia",
        "lat": "-42.89633222",
        "lon": "147.32279777"
    }
}

5) Notes on Return Values

Not all of the values in the previously given example will be present in every result. That example gives all POSSIBLE return values. For example, a result that is POSTCODE_LEVEL may not include house_number, street_name, etc with the exception of countries like Ireland and Singapore where the Postcode is specific to a given address. Read on for details of specific sections, what they may return, and what those values mean.

6) 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": 316,
            "paid_left": 0,
            "expires": "2025-12-22 22:20:54"
        },
        "query": {
            "type": "PAID",
            "allow": true,
            "allow_reason": "UNLIMITED_ACCOUNT",
            "method": "REVERSE",
            "requested": "-42.896346,147.322658",
            "found": true,
            "time_taken": "79ms"
        }
    },

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 useful 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 "REVERSE".
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".

7) The "result" section

Here is an example of the result section:

    "result": {
        "id": "210708",
        "match_type": "ADDRESS_LEVEL",
        "full_address": "50 Regent St, Sandy Bay, TAS 7005, Australia",
        "house_number": "50",
        "street_name": "Regent St",
        "street_full": "50 Regent St",
        "postcode": "7005",
        "admin3_name": "Sandy Bay",
        "admin3_type": "Locality",
        "admin2_name": "Hobart",
        "admin2_type": "City",
        "admin1_short": "TAS",
        "admin1_long": "Tasmania",
        "admin1_type": "State",
        "country_alpha2": "AU",
        "country_alpha3": "AUS",
        "country_short": "Australia",
        "country_long": "Commonwealth of Australia",
        "lat": "-42.89633222",
        "lon": "147.32279777"
    }

The result section MAY contain the following fields(not all for every match_type). Note that this is the format for only land-based searches. For maritime searches (seas, oceans, etc) see the next section on Marintime Results:

id = Will always be returned, regardless of match_type. This is the ID of the polygon this match was found inside of in our database. Useful when contacting support regarding inaccurate or invalid data, allowing us to quickly troubleshoot the offending record(s).
match_type = Will always be returned. May contain any of the following:
- ADDRESS_LEVEL = Result is a direct address hit. All address details should be provided in the rest of result.
- POSTCODE_LEVEL = Result is a postcode match. Postcode should return all other admin-level details where applicable. In some countries, such as Ireland, a postcode may return full address details where the postcode is equivalent to an address.
- ADMIN5_LEVEL = Result is an Administrative Level 5 match. Few countries have this level (only France and Rwanda). The most specific admin level, such as a village.
- ADMIN4_LEVEL = Result is an Administrative Level 4 match. Few countries have this level. Could be a village or borough.
- ADMIN3_LEVEL = Result is an Administrative Level 3 match. Most countries have this level. Could be a city or town.
- ADMIN2_LEVEL = Result is an Administrative Level 2 match. Most countries have this level. Could be a county or region.
- ADMIN1_LEVEL = Result is an Administrative Level 1 match. Most countries have this level. Could be a province or state.
- COUNTRY_LEVEL = Result is an Country Level match. No other Administrative Regions were found to cover this point.
full_address = Always returned. Will contain the formatted address for the returned result.
house_number = The house number along the given street_name. Not always returned.
street_name = The full name of the street that an address is on. Not always returned.
street_full = The house number and street name combined. Not always returned.
postcode = The postcode or zipcode where a match is found. Not always returned.
admin5_name = The name of the Administrative Level 5 match. Not always returned.
admin5_type = The type of the Administrative Level 5 division. Not always returned.
admin4_name = The name of the Administrative Level 4 match. Not always returned.
admin4_type = The type of the Administrative Level 4 division. Not always returned.
admin3_name = The name of the Administrative Level 3 match. Not always returned.
admin3_type = The type of the Administrative Level 3 division. Not always returned.
admin2_name = The name of the Administrative Level 2 match. Not always returned.
admin2_type = The type of the Administrative Level 2 division. Not always returned.
admin1_short = The shortened name or abbreviation of the Administrative Level 1 division. Not always returned. Where abbreviations or short names aren't used, this may be the same as the admin1_long result.
admin1_long = The long or full name of the Administrative Level 1 division. Not always returned.
admin1_type = The type of the Administrative Level 1 division. Not always returned.
country_alpha2 = Always returned. The ISO Alpha2 country code.
country_alpha3 = Always returned. The ISO Alpha3 country code.
country_short = Always returned. Commonly used short country name.
country_long = Always returned. Full legal country name.
lat = Always returned. The centroid latitude of the polygon that the result was found in.
lon = Always returned. The centroid longitude of the polygon that the result was found in.

8) Maritime Results

Here is an example of the result section for maritime results:

    "result": {
        "id": "6000000007",
        "match_type": "MARITIME_LEVEL",
        "type": "Ocean",
        "name": "Atlantic Ocean",
        "area": "40270000",
        "lat": "-34.006912",
        "lon": "-18.916816"
    }

The result section will always contain the following fields for maritime results:

id = Will always be returned. This is the ID of the polygon this match was found inside of in our database. Useful when contacting support regarding inaccurate or invalid data, allowing us to quickly troubleshoot the offending record(s).
match_type = Will always return "MARITIME_LEVEL" for Maritime Matches.
type = May contain any of the following:
- Ocean
- Sea
- Reef
- Bay
- Gulf
- Strait
- Channel
- Sound
- Fjord
- Lagoon
- Generic
- Inlet
- River
name = Contains the name of the body of water
area = Contains a numeric value indicating the total area covered by the body of water in km2.
lat = The centroid latitude of the polygon that the result was found in.
lon = The centroid longitude of the polygon that the result was found in.

BACK TO HOMEPAGE