Geocodify API Documentation

Version 2.0.0.1

SVG
SVG

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.