Geocodify API Documentation

Version 2.0.0.1

We are excited to announce the release of Geocodify API Version 2.0, which now supports an expanded range of data points. To take advantage of the new features, please ensure to update your API calls to use version 2.0. For any inquiries or assistance, feel free to reach out to us at [email protected].

Welcome to 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 and enterprise-grade geocoding services, catering to developers, startups, and enterprises across the globe, handling millions of requests daily. This documentation aims to provide a detailed technical overview of the Geocodify API, guiding you through the initial setup and exploring the various functionalities it offers.

We work with developers, startups and enterprises worldwide serving millions of requests daily. This page provides an overview of the technical aspects of our API and will help you get started.

Geocodify API adheres to RESTful principles, allowing authenticated users to interact with our resources using standard HTTP methods. We prioritize security by mandating SSL encryption for all requests, which should be made via HTTPS.

Quick Start

Before we get to all the details and possible options that our API provides, below is a quick start 2-step guide to get you started very quickly.

Step 1: Get your api_key from the account dashboard by visiting this link.

Step 2: Start geocoding by requesting a URL:

Forward Geocoding

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

Reverse Geocoding

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

Auto Complete

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

Geoparsing

https://api.geocodify.com/v2/geoparse
    ?api_key=_api_key_goes_here_
    &text=I'm taking the 6AM out of New York, 
    landing at 9am in LA and from there hopping onto a connecting flight to Sydney, Australia.

Address Parsing

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

Elevation

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

Authentication

An API key is required for every request to the API. Your API key is used to authenticate you with our API, and it should be provided as a api_key URL parameter.

The API key can be retrieved from the account pages. If you do not know your API key please signup for a free account key.

 ?api_key=baa9dc110aa712sd3a9fa2a3dwb6c01d4c875950dc32vs

The api_key should be appended to the url request like in the example below

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

API Base URL

https://api.geocodify.com/v2

API Endpoints

`/geocode`	This provides the longitude, latitude, and place details based on a search query, whether it's an address, the name of a place, or a location..
`/reverse`	This endpoint takes a point coordinate(longitutde and and laatitude) and returns a list of all address, points and items located at that location.
`/geoparse`	Using a TensorFlow backend, this endpoint takes a free-text descriptions of places (such as "Springfield") and converts it into unambiguous geographic identifiers (such as lat-lon coordinates).
`/autocomplete`	This endpoint allows you to access real-time address and location result suggestions without having to type the whole location or address.
`/parse`	This endpoint is allows you to parse and normalize street addresses around the world.

Forward Geocoding Endpoint

The Search API allows converting addresses, such as a street address, into geographic coordinates (latitude and longitude). These coordinates can serve various use-cases, from placing markers on a map to helping algorithms determine nearby bus stops. This process is also known as Forward Geocoding. OUr API returns GeoJSON.

Name	Description	Required
`api_key`	Your API Key	Yes
`q`	Free-form query string to search for. Commas are optional, but improves performance by reducing the complexity of the search. Do not combine with structured/postalcode parameters	Yes

Reverse Geocoding Endpoint

Reverse geocoding is the process of converting a coordinate or location (latitude, longitude) to a readable address or place name. This permits the identification of nearby street addresses, places, and/or area subdivisions such as a neighborhood, county, state, or country.

Name	Description	Required
`api_key`	Your API Key	Yes
`lng`	Latitude of the location to generate an address for.	Yes
`lat`	Longitude of the location to generate an address for.	Yes

Autocomplete Geocoding Endpoint

The Autocomplete API is a variant of the Search API that returns place predictions in response to an HTTP request. The request specifies a textual search string and optional geographic bounds. The service can be used to provide autocomplete functionality for text-based geographic searches, by returning places such as businesses, addresses and points of interest as a user types. The Autocomplete API can match on full words as well as substrings. Applications can therefore send queries as the user types, to provide on-the-fly place predictions.

Name	Description	Required
`api_key`	Your API Key	Yes
`q`	An address or part of it	Yes

Geoparsing Endpoint

Using a TensorFlow backend, this endpoint takes a free-text descriptions of places (such as "Springfield") and converts it into unambiguous geographic identifiers (such as lat-lon coordinates).

Name	Description	Required
`api_key`	Your API Key	Yes
`text`	Free-form text to geo parse	Yes

Address Parsing Endpoint

Using libparser, we parse out unstructured addresses into a structured addresses with parts.

Name	Description	Required
`api_key`	Your API Key	Yes
`q`	Address text	Yes

HTTP response codes

Every API request returns an appropriate HTTP response code and below is a list of what they mean with regards to the API

`200`	Success Everything went smooth.
`401`	Unauthorized Missing or incorrect API token in header.
`422`	Un-processable Entity meaning something with the message isn’t quite right, this could be malformed JSON or incorrect fields. In this case, the response body contains JSON with an API error code and message containing details on what went wrong.
`500`	Internal Server Error This is an issue with Geocodify's servers processing your request. In most cases the message is lost during the process, and we are notified so that we can investigate the issue.
`503`	Service Unavailable During planned service outages, Geocodify API services will return this HTTP response and associated JSON body.
`429`	Too many requests. API limits reached.

API error codes

Whenever the Geocodify server detects an input error it will return an HTTP 422 status code along with a JSON object containing error details:

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

JSON Response

We try to automatically detect when someone wants to call our API vs view our website, and send back the appropriate JSON response rather than HTML. We do this based on the user agent for known popular programming languages, tools and frameworks. There are a couple of other ways to force a JSON response from us in the cases that it doesn't happen automatically though. One is to add /json to the URL, and the other is to set an accepts header to application/json:

Rate Limits

Free trial users are limited to 1 request per second and if you exceed that rate you may be blocked. Paying customers can use our service at a much faster rate, ranging from 10-15 requests per second depending on pricing tier. Please see the exact levels on our pricing page. If you need more than 25 requests per second (our Large plan) please get in touch to discuss your exact needs. If you request too quickly you will eventually see a 429 - Too many requests response. Please refer to the section above for all possible response codes and an API key you can use to generate a 429 response for testing.

CORS / JSONP

If you are accessing the API from client side javascript please be aware that by default the Geocodify API allows all origins for Cross-Origin Resource Sharing (CORS).

Learn more about CORS on Wikipedia. There you can also read some of the pros and cons of JSONP and CORS.

Help Us Improve

While we have been in the industry for years, Geocoding the world is a very challenging task, we would love your help. If anything in this documentation is unclear, please let us know by emailing us at [email protected]. We appreciate your feedback and will work with you to get better.