Geocodify API Documentation

Version 2.0.0.1

New Release: Geocodify API Version 2.0.0.1 is now available with an expanded range of data points. Please ensure you update your API calls to use version 2.0 features. For assistance, contact us at [email protected].

Introduction

Welcome to the Geocodify API, a comprehensive solution for location intelligence. Our database encompasses over 500 million addresses and points of interest (POIs), covers 4.8 million cities, and maps out 110 million streets globally.

Geocodify is designed to offer simple yet robust enterprise-grade geocoding services, catering to developers, startups, and enterprises across the globe, handling millions of requests daily.

This documentation provides a detailed technical overview of the Geocodify API, guiding you through the initial setup and exploring the various functionalities it offers. Adhering to RESTful principles, our API allows authenticated users to interact with resources using standard HTTP methods. We prioritize security by enforcing SSL encryption (HTTPS) for all requests.

Quick Start

Get started quickly with our 2-step guide:

Step 1: Get your API Key

Obtain your unique api_key from your account dashboard.

Step 2: Make a Request

Try these examples immediately:

Forward Geocoding

https://api.geocodify.com/v2/geocode?api_key=YOUR_API_KEY&q=900 Boston Post Road, Guilford Center, CT, USA

Reverse Geocoding

https://api.geocodify.com/v2/reverse?api_key=YOUR_API_KEY&lat=40.6892&lng=74.0445

Autocomplete

https://api.geocodify.com/v2/autocomplete?api_key=YOUR_API_KEY&q=900 Boston Post Road

Geoparsing

https://api.geocodify.com/v2/geoparse?api_key=YOUR_API_KEY&text=I'm taking the 6AM flight out of New York to Los Angeles.

Address Parsing

https://api.geocodify.com/v2/parse?api_key=YOUR_API_KEY&address=900 Boston Post Road, Guilford Center, CT, USA

Elevation

https://api.geocodify.com/v2/elevation?api_key=YOUR_API_KEY&lat=40.6892&lng=74.0445

Authentication

An API key is required for every request. This key authenticates you with our API and must be provided as an api_key URL parameter.

If you do not have an API key, please sign up for a free account to get one.

Example of appending the API key:

curl -G https://api.geocodify.com/v2/geocode?api_key=YOUR_API_KEY

API Base URL

https://api.geocodify.com/v2

API Endpoints

Endpoint	Description
`/geocode`	Returns longitude, latitude, and place details based on a search query (address, place name, or location).
`/reverse`	Takes coordinate points (longitude and latitude) and returns a list of addresses, points of interest, and items at that location.
`/geoparse`	Uses a TensorFlow backend to convert free-text descriptions of places (e.g., "Springfield") into unambiguous geographic identifiers (lat/lon).
`/autocomplete`	Access real-time address and location suggestions as you type.
`/parse`	Parses and normalizes unstructured international street addresses into structured components.
`/elevation`	Returns elevation data for a specific latitude and longitude.
`/status`	Returns the current status of the API services.

Endpoint Reference

Forward Geocoding (`/geocode`)

Converts addresses (e.g., "1600 Amphitheatre Parkway") into geographic coordinates (latitude and longitude).

Parameter	Required	Description
`api_key`	Yes	Your unique API authentication key.
`q`	Yes	The free-form query string to search for (e.g., address, city).

Reverse Geocoding (`/reverse`)

Converts geographic coordinates (latitude, longitude) into a readable address or place name.

Parameter	Required	Description
`api_key`	Yes	Your unique API authentication key.
`lat`	Yes	Latitude of the location.
`lng`	Yes	Longitude of the location.
`limit`	No	Number of results to return (default: 10).

Autocomplete (`/autocomplete`)

Returns place predictions in response to a textual search string. Ideal for "search-as-you-type" functionality.

Parameter	Required	Description
`api_key`	Yes	Your unique API authentication key.
`q`	Yes	The address text or substring to search for.

Geoparsing (`/geoparse`)

Extracts and disambiguates geographic entities from unstructured text.

Parameter	Required	Description
`api_key`	Yes	Your unique API authentication key.
`text`	Yes	The free-form text containing location names to parse.

Address Parsing (`/parse`)

Parses an address string into its component parts (number, street, city, postal code, etc.).

Parameter	Required	Description
`api_key`	Yes	Your unique API authentication key.
`address`	Yes	The address string to parse. (Note: Previously documented as 'q')

Elevation (`/elevation`)

Retrieves elevation data (in meters) for a specific coordinate.

Parameter	Required	Description
`api_key`	Yes	Your unique API authentication key.
`lat`	Yes	Latitude of the location.
`lng`	Yes	Longitude of the location.

HTTP Response Codes

The API generally uses the following HTTP status codes. Note that in some cases, a 200 OK may be returned even if usage limits are reached or parameters are missing, with details in the JSON meta field.

`200`	Success. The request was processed successfully.
`401`	Unauthorized. Missing or incorrect API key.
`422`	Unprocessable Entity. Usually indicates malformed parameters or validation errors. Check the error message body.
`429`	Too Many Requests. You have exceeded your rate limit.
`500`	Internal Server Error. An issue occurred on our end. We are notified automatically.
`503`	Service Unavailable. The API is temporarily offline for maintenance.

API Error Codes

JSON error responses may include specific internal error codes:

`600`	Maintenance: The Geocodify API is offline for maintenance.
`601`	Unauthorized: Missing or incorrect API key.
`602`	Invalid query parameters.
`603`	Authorized Subscription level required.

JSON Response

The API defaults to returning JSON responses. You can forcefully ensure a JSON response by setting the Accept header to application/json.

Rate Limits

Free Trial: Limited to 1 request per second.
Paid Plans: 10-25+ requests per second depending on your tier.

If you exceed these limits, you will receive a 429 Too Many Requests response. Please review our pricing page for detailed tier limits or contact us for enterprise needs.

CORS / JSONP

The Geocodify API supports Cross-Origin Resource Sharing (CORS) by default, allowing you to call the API directly from client-side JavaScript.

Support & Feedback

Geocoding the world is a complex challenge, and we value your feedback. If you find any issues with this documentation or the API, please email us at [email protected].