Batch Forward Geocoding API

1. The Geocode.Farm Batch Forward Geocoding API processes multiple addresses (up to 1000) in a single request.
2. Requests are queued and processed asynchronously.
3. API authentication is required via an API key.
4. A result URL is provided for retrieving processed results.

1. POST https://api.geocode.farm/batch-forward/

1. API keys are required for all requests.
2. Include the key as a JSON parameter in the POST body.

{
    "key": "YOUR-API-KEY-HERE",
    "addresses": [
        "SHERIDAN, WY, USA",
        "123 MAIN ST, SYDNEY, AUSTRALIA"
    ]
}

{
    "LEGAL": {
        "notice": "This system is the property of Geocode.Farm and any information contained herein is Copyright (c) Geocode.Farm. Usage is subject to the Terms of Service.",
        "terms": "https://geocode.farm/policies/terms-of-service/",
        "privacy": "https://geocode.farm/policies/privacy-policy/"
    },
    "STATUS": {
        "key": "VALID",
        "request": "VALID",
        "status": "SUCCESS",
        "credit_used": 2
    },
    "USER": {
        "key": "YOUR-API-KEY-HERE",
        "name": "Your Name",
        "email": "yourname@yourdomain.com",
        "usage_limit": "UNLIMITED",
        "used_today": 2,
        "remaining_limit": "UNLIMITED"
    },
    "REQUEST": {
        "status": "PENDING",
        "entities": 2,
        "created": "2025-04-04 14:55:10",
        "expires": "2025-04-07 14:55:10",
        "result_url": "https://api.geocode.farm/batch-forward/result/?id=BATCH_ID_WILL_BE_HERE&key=YOUR-API-KEY-HERE"
    }
}

STATUS

• key: Indicates API key validity ("VALID" or "INVALID").
• request: Whether the request was valid ("VALID" or "INVALID").
• status: Request status ("SUCCESS" or "FAILED").
• credit_used: Number of API credits used (equal to number of addresses provided).

USER

• key: API key used in the request.
• name: Registered name.
• email: Registered email address.
• usage_limit: Daily query limit.
• used_today: Number of requests made today.
• remaining_limit: Remaining requests available today.

REQUEST

• status: Current processing state (e.g., "PENDING","PROCESSING","DONE","EXPIRED").
• entities: Number of addresses submitted.
• created: Timestamp of request creation.
• expires: Timestamp of when result will no longer be available.
• result_url: URL to fetch geocoding results after processing.

When the batch geocoding request has finished processing, the results can be retrieved using the result_url provided in the initial response.

REQUEST Section

• status:
  • PENDING – Request has been received and queued, but not yet processed.
  • PROCESSING – Request is currently being processed.
  • DONE – Processing is complete. The RESULTS array will be included.
  • EXPIRED – The result has expired and is no longer retrievable.
• entities: Number of address strings originally submitted.
• created: Timestamp indicating when the request was submitted.
• expires: Timestamp after which the result will no longer be available.

RESULTS Section

This section is only returned when REQUEST.status = "DONE". Each submitted address will have a corresponding result object.

Example Results Response

{
    "LEGAL": {
        "notice": "This system is the property of Geocode.Farm and any information contained herein is Copyright (c) Geocode.Farm. Usage is subject to the Terms of Service.",
        "terms": "https:\/\/geocode.farm\/policies\/terms-of-service\/",
        "privacy": "https:\/\/geocode.farm\/policies\/privacy-policy\/"
    },
    "STATUS": {
        "key": "VALID",
        "request": "VALID",
        "status": "SUCCESS"
    },
    "REQUEST": {
        "status": "DONE",
        "entities": 2,
        "created": "2025-04-04 14:55:10",
        "expires": "2025-04-07 14:55:10"
    },
    "RESULTS": [
        {
            "request": "123 MAIN ST, CITY, COUNTRY",
            "result": {
                "lat": "12.3456789101112",
                "lon": "-123.3456789101112",
                "full_address": "123 Main St, City, Country",
                "house_number": "123",
                "street_name": "Main St",
                "neighborhood": "Some Neighborhood",
                "locality": "City",
                "admin_3": "Municipality",
                "admin_2": "County Name",
                "admin_1": "State or Province",
                "country": "Country Name",
                "postal_code": "90210"
            }
        },
        {
            "request": "UNKNOWN ADDRESS",
            "result": "NO_RESULTS"
        }
    ]
}

RESULTS Array Fields

• request: The original address string as submitted.
• result: A result object with geocoded details, or "NO_RESULTS" if the address could not be matched.

Possible Fields in a result Object:

• lat: Latitude of the matched location.
• lon: Longitude of the matched location.
• full_address: Formatted and normalized address string.
• house_number: House or building number (if detected).
• street_name: Street or road name (if detected).
• neighborhood: Neighborhood or small area name (if available).
• locality: City or town.
• admin_3: Third-level administrative division (e.g., municipality, district).
• admin_2: Second-level administrative division (e.g., county or borough).
• admin_1: First-level administrative division (e.g., state or province).
• country: Country name.
• postal_code: ZIP or postal code.

Note: Not all fields will be present in every result. Fields are included based on the availability of data.

The following are provided with each result as HTTP Status Codes:

• 200 - Batch accepted and queued for processing.
• 400 - Problem With jSON Input. (too many addresses or bad format)
• 401 - API key is invalid or missing.
• 402 - No credit available or expired account
• 500 - An unexpected error occurred. Contact support if issue persists.