• “Nothing works better than just improving your product.” —Joel Spolsky, Stack Overflow








API DOCUMENTATION

Updated: 15-JAN-2015

THE API:

We operate a standard REST compliant API service. The API has two operations, forward and reverse. There are two formats available for returned data, JSON and XML. JSON is the most popular format used due to its light-weight and fast processing ability.

Free usage does not require an API Key and the free limit is 250 per day per IP address.


USAGE LIMITS:

    1. Free Users Have 250 Per Day Limit and 4 Requests Per Second Limit (IP Based)
    2. 25,000 Per Day Plan Users Have A Rate Limit of 7 Requests Per Second (API Key Based)
    3. 50,000 Per Day Plan Users Have A Rate Limit of 14 Requests Per Second (API Key Based)
    4. 100,000 Per Day Plan Users Have A Rate Limit of 28 Requests Per Second (API Key Based)
  1. These limits are enforced to prevent abuse and/or repurposing of the API, and may be changed in the future with or without notice. If you abuse the service your access to the API may be blocked with or without notice.
  2. All account limits are reset each day at midnight, US Eastern Time (GMT-5).
  3. For complete details on allowed usage, consult the Terms of Service, Privacy Policy, SLA, & FAQs.


SENDING REQUESTS:

The following URL format should be used: https://www.geocode.farm/v3/[json|xml]/[forward|reverse]/?parameters

HTTPS is recommended for applications that include sensitive user data, such as a user's location, in requests. Replace "https" with "http" in the URL format provided to disable SSL encryption. SSL encryption may slow down requests as it requires all data to be encrypted and decrypted before and after transmitting.

Some parameters are required while some are optional. As is standard in URLs, parameters are separated using the ampersand (&) character.

Depending on the type of request and the format you would like returned, the URL structure will vary. Please see the specific sections for FORWARD GEOCODING REQUESTS and REVERSE GEOCODING REQESTS located below for further details. The rest of this page describes Forward Geocoding Requests and Reverse Geocoding Requests separately, because different parameters are available for each type of request.


FORMATTING ADDRESS:

Formatting in the address request is very simple.

For full addresses, just send the request in the same format you would use for a piece of mail (eg. 530 W Main St Anoka MN 55303 US). Just be sure to include the country at the end of the address to ensure accurate results.

For zip codes, send the zip code along with the country in your request (eg. 55303 US).

International addresses and characters are permitted by the API.


FORWARD GEOCODING REQUESTS:

Forward geocoding takes a provided address or location and returns the coordinate set for the requested location.

  1. Required parameters for Forward Geocoding Requests:
    1. addr — The string to search for. Usually a street address. Should be URL encoded prior to sending request.
    2. key — API Key. Only Required for Paid Users. If not sepecified, Free User restrictions will apply. Located in Dashboard for Paid Users. Paid Users should include with every request to avoid Free User limits taking effect. Free Users should not specify or requests may fail due to Invalid API Key response.
  2. Optional parameters for Forward Geocoding Requests:
    1. lang — 2 digit lanuage code to return results in. Currently only "en"(English) or "de"(German) supported.
    2. country — The country to return results in. Used for biasing purposes and may not fully filter results to this specific country.
    3. count — Max amount of results to return. Used for limiting results only and this amount of results will not always be returned. If less results are available then the count specified, all available results will be returned. Default value is 1.

The full URL path can be seen in the following examples:
(JSON) https://www.geocode.farm/v3/json/forward/?addr=530+W+Main+St+Anoka+MN+55303+US&country=us&lang=en&count=1
(XML) https://www.geocode.farm/v3/xml/forward/?addr=530+W+Main+St+Anoka+MN+55303+US&country=us&lang=en&count=1


REVERSE GEOCODING REQUESTS:

Reverse geocoding takes a provided coordinate set and returns the address for the requested coordinates.

  1. Required parameters for Reverse Geocoding Requests:
    1. lat — The numerical latitude value for which you wish to obtain the closest, human-readable address.
    2. lon — The numerical longitude value for which you wish to obtain the closest, human-readable address.
    3. key — API Key. Only Required for Paid Users. If not sepecified, Free User restrictions will apply. Located in Dashboard for Paid Users. Paid Users should include with every request to avoid Free User limits taking effect. Free Users should not specify or requests may fail due to Invalid API Key response.
  2. Optional parameters for Reverse Geocoding Requests:
    1. lang — 2 digit lanuage code to return results in. Currently only "en"(English) or "de"(German) supported.
    2. country — The country to return results in. Used for biasing purposes and may not fully filter results to this specific country.
    3. count — Max amount of results to return. Used for limiting results only and this amount of results will not always be returned. If less results are available then the count specified, all available results will be returned. Default value is 1.

The full URL path can be seen in the following examples:
(JSON) https://www.geocode.farm/v3/json/reverse/?lat=45.2040305&lon=-93.3995728&country=us&lang=en&count=1
(XML) https://www.geocode.farm/v3/xml/reverse/?lat=45.2040305&lon=-93.3995728&country=us&lang=en&count=1


EXAMPLE JSON OUTPUT:

{
    "geocoding_results": {
        "LEGAL_COPYRIGHT": {
            "copyright_notice": "Copyright (c) 2017 Geocode.Farm - All Rights Reserved.",
            "copyright_logo": "https:\/\/www.geocode.farm\/assets\/img\/logo.png",
            "terms_of_service": "https:\/\/www.geocode.farm\/policies\/terms-of-service\/",
            "privacy_policy": "https:\/\/www.geocode.farm\/policies\/privacy-policy\/"
        },
        "STATUS": {
            "access": "FREE_USER, ACCESS_GRANTED",
            "status": "SUCCESS",
            "latitude_provided": "45.2040305",
            "longitude_provided": "-93.3995728",
            "result_count": 1
        },
        "ACCOUNT": {
            "ip_address": "127.0.0.1",
            "distribution_license": "NONE, UNLICENSED",
            "usage_limit": "250",
            "used_today": "101",
            "used_total": "251",
            "first_used": "2017-02-23 02:22:32"
        },
        "RESULTS": [
            {
                "result_number": 1,
                "formatted_address": "522-534 West Main Street, Anoka, MN 55303, USA",
                "accuracy": "HIGH_ACCURACY",
                "ADDRESS": {
                    "street_number": "522-534",
                    "street_name": "West Main Street",
                    "locality": "Anoka",
                    "admin_2": "Anoka County",
                    "admin_1": "Minnesota",
                    "postal_code": "55303",
                    "country": "United States"
                },
                "LOCATION_DETAILS": {
                    "elevation": 868.67,
                    "timezone_long": "Central Standard Time",
                    "timezone_short": "America\/Chicago"
                },
                "COORDINATES": {
                    "latitude": "45.2040307639451",
                    "longitude": "-93.3995726274743"
                },
                "BOUNDARIES": {
                    "northeast_latitude": "45.2040307758898",
                    "northeast_longitude": "-93.3995726521629",
                    "southwest_latitude": "45.2026515197081",
                    "southwest_longitude": "-93.4008553302914"
                }
            }
        ],
        "STATISTICS": {
            "https_ssl": "ENABLED, SECURE"
        }
    }
}


EXAMPLE XML OUTPUT:

–<geocoding_results>
  –<LEGAL_COPYRIGHT>
    <copyright_notice>
    Copyright (c) 2017 Geocode.Farm - All Rights Reserved.
    </copyright_notice>
    <copyright_logo>https://www.geocode.farm/assets/img/logo.png</copyright_logo>
    <terms_of_service>https://www.geocode.farm/policies/terms-of-service/</terms_of_service>
    <privacy_policy>https://www.geocode.farm/policies/privacy-policy/</privacy_policy>
   </LEGAL_COPYRIGHT>
  –<STATUS>
    <access>FREE_USER, ACCESS_GRANTED</access>
    <status>SUCCESS</status>
    <latitude_provided>45.2040305</latitude_provided>
    <longitude_provided>-93.3995728</longitude_provided>
    <result_count>1</result_count>
   </STATUS>
  –<ACCOUNT>
    <ip_address>127.0.0.1</ip_address>
    <distribution_license>NONE, UNLICENSED</distribution_license>
    <usage_limit>250</usage_limit>
    <used_today>101</used_today>
    <used_total>251</used_total>
    <first_used>2017-02-23 02:22:32</first_used>
   </ACCOUNT>
  –<RESULTS>
    –<result>
      <result_number>1</result_number>
      <formatted_address>522-534 West Main Street, Anoka, MN 55303, USA</formatted_address>
      <accuracy>HIGH_ACCURACY</accuracy>
     –<ADDRESS>
        <street_number>522-534</street_number>
        <street_name>West Main Street</street_name>
        <locality>Anoka</locality>
        <admin_2>Anoka County</admin_2>
        <admin_1>Minnesota</admin_1>
        <postal_code>55303</postal_code>
        <country>United States</country>
      </ADDRESS>
     –<LOCATION_DETAILS>
        <elevation>868.67</elevation>
        <timezone_long>Central Standard Time</timezone_long>
        <timezone_short>America/Chicago</timezone_short>
      </LOCATION_DETAILS>
     –<COORDINATES>
        <latitude>45.2040307639451</latitude>
        <longitude>-93.3995726274743</longitude>
      </COORDINATES>
     –<BOUNDARIES>
        <northeast_latitude>45.2040307758898</northeast_latitude>
        <northeast_longitude>-93.3995726521629</northeast_longitude>
        <southwest_latitude>45.2026515197081</southwest_latitude>
        <southwest_longitude>-93.4008553302914</southwest_longitude>
      </BOUNDARIES>
     </result>
   </RESULTS>
  –<STATISTICS>
    <https_ssl>ENABLED, SECURE</https_ssl>
   </STATISTICS>
 </geocoding_results>


RESPONSE FIELDS BREAKDOWN:

  1. "access" FIELD RESPONSES:
  2. This field describes the potential problems and issues that may be denying access. It will also inform you if access has been granted. The possible responses are as follows:

  3. "status" FIELD RESPONSES:
  4. This field describes the status of your particular query. The three(3) available statuses are as follows:

  5. "accuracy" FIELD RESPONSES:
  6. This field describes the accuracy of your particular query's result in relevance to the original query. This field's response varies greatly based on the particular query and the algorithm that we use for this is very complex causing it to be harder to describe these results. Below are the available responses for this field:

  7. "distribution_license" FIELD RESPONSES:
  8. "address_provided" FIELD: The "addr" URL paremeter value provided in the request.
  9. "latitude_provided" FIELD: The "lat" URL paremeter value provided in the request.
  10. "longitude_provided" FIELD: The "lon" URL paremeter value provided in the request.
  11. "result_count" FIELD: Returns the number of results in the returned result set.
  12. "result_number" FIELD: The number of this result in the returned result set. Starts at 1.
  13. "formatted_address" FIELD: A string containing the human-readable address of this location. Often this address is equivalent to the "postal address," which sometimes differs from country to country.
  14. "street_number" FIELD: Indicates the precise or estimated street/house/building number.
  15. "street_name" FIELD: Indicates the full name of the street level element or route.
  16. "admin_1" FIELD: Indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels.
  17. "admin_2" FIELD: Indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels.
  18. "admin_3" FIELD: Indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  19. "locality" FIELD: Indicates an incorporated city or town political entity.
  20. "neighborhood" FIELD: Indicates a named neighborhood.
  21. "postal_code" FIELD: Indicates a postal code as used to address postal mail within the country.
  22. "country" FIELD: Indicates the national political entity, and is typically the highest order type returned by the API.
  23. "elevation" FIELD: Indicates the elevation of the point in US Standard Feet.
  24. "timezone_long" FIELD: The full human-readable timezone name for the returned point.
  25. "timezone_short" FIELD: The short or abreviated timezone name. Mostly as used by *NIX systems.
  26. "latitude" FIELD: The human and computer readable latitude returned for this result. The first half of a coordinate pair.
  27. "longitude" FIELD: The human and computer readable longitude returned for this result. The second half of a coordinate pair.
  28. "BOUNDARIES" FIELD(s): The northeast_latitude, northeast_longitude, southwest_latitude, & southwest_longitude of the result.
  29. "https_ssl" FIELD: Returns "ENABLED, SECURE" if SSL is enabled or "DISABLED, INSECURE" if SSL is disabled for this request.

* This Documentation is subject to change.