Reverse Geocoding API

  1. Overview

    1. The Geocode.Farm Reverse Geocoding API returns a structured address based on latitude and longitude coordinates.
    2. API authentication is required via an API key.

  2. Base URL

    1. GET https://api.geocode.farm/reverse/

  3. Authentication

    1. API keys are required for all requests.
    2. Provide the key using the key parameter in the URL.

  4. Request Parameters

    5. ParameterTypeRequiredDescription
    key string Yes Your API key for authentication.
    lat string/number Yes The latitude coordinate to be reverse geocoded.
    lon string/number Yes The longitude coordinate to be reverse geocoded.

  5. Example Request

    6. GET https://api.geocode.farm/reverse/?key=YOUR-API-KEY-HERE&lat=44.7977733966548&lon=-106.954917523499

  6. Example Response

    7. {
    "LEGAL": {
        "notice": "This system is the property of Geocode.Farm...",
        "terms": "https:\/\/geocode.farm\/policies\/terms-of-service\/",
        "privacy": "https:\/\/geocode.farm\/policies\/privacy-policy\/",
        "sla": "https:\/\/geocode.farm\/policies\/service-level-agreement\/"
    },
    "STATUS": {
        "key": "VALID",
        "status": "SUCCESS",
        "request": "VALID",
        "credit_used": "1"
    },
    "USER": {
        "key": "YOUR-API-KEY-HERE",
        "name": "Your Name",
        "email": "yourname@yourdomain.com",
        "usage_limit": "UNLIMITED",
        "used_today": "1",
        "remaining_limit": "UNLIMITED"
    },
    "RESULTS": {
        "request": {
            "lat": "44.7977733966548",
            "lon": "-106.954917523499"
        },
        "result": {
            "coordinates": {
                "lat": "44.7977733966548",
                "lon": "-106.954917523499"
            },
            "address": {
                "full_address": "30 N Gould St, Sheridan, WY 82801, United States",
                "house_number": "30",
                "street_name": "N Gould St",
                "locality": "Sheridan",
                "admin_2": "Sheridan County",
                "admin_1": "WY",
                "country": "United States",
                "postal_code": "82801"
            },
            "accuracy": "EXACT_MATCH"
        }
    }
}

  7. Response Fields

    8. STATUS
    • key: Indicates API key validity ("VALID" or "INVALID").
    • status: Request status ("SUCCESS" or "FAILED").
    • request: Whether the request was valid ("VALID" or "INVALID").
    • credit_used: Number of API credits or plan queries consumed. Will be 0 on failed requests.
    USER
    • key: API key used in the request.
    • name: Registered name.
    • email: Registered email.
    • usage_limit: Daily API query limit (e.g., "UNLIMITED" or a set number).
    • used_today: Number of requests made today.
    • remaining_limit: Remaining query limit for today.
    RESULTS
    • request: The originally requested coordinates.
    • result: Contains reverse geolocation details:
      • coordinates: The latitude and longitude as processed.
      • address: Structured address data including full address, street details, locality, and postal code.
      • accuracy: Quality of match (e.g., "EXACT_MATCH", "HIGH_ACCURACY", "MEDIUM_ACCURACY", "LOW_ACCURACY", or "UNKNOWN_ACCURACY").

  8. Error Status Codes

    9. The following HTTP Status Codes may be returned with each result:

    • 200 - Results returned successfully.
    • 400 - Missing or invalid latitude/longitude parameters.
    • 401 - API key is invalid or missing.
    • 402 - No credit available or expired API key.
    • 404 - No matching results found.
    • 429 - Rate limit exceeded.
    • 500 - An unexpected error occurred. Contact support if this error persists.


Last Updated: 22-MAR-2025