Geolake

Geolake Introduction

This page outlines the usage for the APIs provided by Geolake. Currently code examples are only provided in the form of cURL commands, but these should be easily adapted to your application's environment.

The base URL for all API calls is: https://api.geolake.com/geocode?api_key=XYZ

# Test URL

https://api.geolake.com/geocode?api_key=XYZ&q=San+Francisco

Authentication

Every API call needs to use an API key for authentication. You can generate one or more API keys on the My Account page. Add your key using the api_key querystring parameter.

Address Components

If you have your address data broken down into address components, you can provide those separately.
You don't have to provide all components, but you are encouraged to provide as many components as you have.
If you have an 'address line 1' that is already split out into a street name, house number and sub number (e.g. suite), you can pass in those components separately and leave the address parameter empty.

All fields in the response structure are optional as well, and their presence will vary between regions and addresses.

Request parameters

country:
string The country code in ISO-3166-1 alpha-2 format, e.g. US or CA.
countryCodes:
string Comma separated list of country codes that are allowed for this request. The country codes should be in ISO-3166-1 alpha-2 format, e.g. US or CA. This can be used if you have data from a few specific countries, but do not have accurate country codes per address. The other address components will be used to determine the most appropriate country code per request.
state:
string Abbreviated state name, e.g. NY.
city:
string City name
zipcode:
string Zipcode or equivalent.
address:
string If your don't have a separate street name, house number and sub number, you can provide the equivalent of 'address line 1' here.
street:
string If you have a separate street name, house number and sub number, you can specify the street name here.
houseNumber:
string If you have a separate street name, house number and sub number, you can specify the house number here.
subNumber:
string If you have a separate street name, house number and sub number, you can specify the sub number here. This can for instance be the suite or apartment number.

Response parameters

success:
boolean True if the input could be geocoded.
errorMessage:
string This is optional, and can show more information if success is false.
latitude:
number The latitude with at most 6 decimals precision.
longitude:
number The longitude with at most 6 decimals precision.
accuracyType:
string The accuracy type of the geolocation. Options are: rooftop, interpolated (street range), street, city, zipcode, iprange.
place:
Place object Meta information about the geolocation.

Place parameters

countryCode:
string The country code in ISO-3166-1 alpha-2 format, e.g. US or CA
countryName:
string Display name for the country, e.g. 'United States'
currencyCode:
string The currency code in ISO-4217 format, e.g. 'USD'
timezone:
string The timezone at this location. This is the IANA timezone id, e.g. 'America/New_York'
tld:
string The top level domain for this location, e.g. '.us'.
city:
string (BETA) The mailing-specific city name to use to reach this location, e.g. 'New York'
zipcode:
string (BETA) (US-ONLY) The zip+4 for US addresses, e.g. '12345+6789'
congrDistrict:
string (BETA) (US-ONLY) The congressional district for this location, starting with the geographical state abbreviation, followed by the district number or 'AL' (At Large), e.g. 'DE-AL' or 'PA-1'

https://api.geolake.com/geocode?api_key=XYZ&country=US&state=CA&city=San+Francisco&address=123+Your+Street+Name+Here

# Object Response
{
  "success": true,
  "latitude": 37.760676,
  "longitude": -122.436783,
  "accuracyType": "city",
  "typoCorrected": false,
  "place": {
    "countryCode": "US",
    "countryName": "United States",
    "currencyCode": "USD",
    "timezone": "America/Los_Angeles",
    "tld": ".us",
    "city": "San Francisco"
  }
} 

Full Address

If your address data is not broken down into components, just send in the entire address in the q parameter.

Request parameters

q:
string The entire address as one address query

https://api.geolake.com/geocode?api_key=XYZ&q=123+Your+Street+Name+Here,+San+Francisco+,+CA

IP Geocoding

To geocode an IP address, send in the ip querystring parameter, with the IP in IPv4 format.

Request parameters

ip:
string IPv4 address in the format '1.2.3.4'.

https://api.geolake.com/geocode?api_key=XYZ&ip=127.0.0.1

# Object Response
{
  "success": true,
  "latitude": 37.760676,
  "longitude": -122.436783,
  "accuracyType": "iprange",
  "typoCorrected": false,
  "place": {
    "countryCode": "US",
    "countryName": "United States",
    "currencyCode": "USD",
    "timezone": "America/Los_Angeles",
    "tld": ".us",
    "city": "San Francisco"
  }
}

Errors

If a geocoding request fails, the resulting body will be a JSON object where the key success is set to false.

Attributes

success:
boolean Whether the request succeeded
errorMessage:
string Optional. If an expected error happens, this will be the error message. E.g. 'Not found' if an address is not found.
HTTP Status codes:

200 OK - Everything worked

400 Bad Request - The request was badly built

401 Unauthorized - Invalid API key

402 Request Failed - The request failed, which can happen if the address can't be geocoded

404 Not Found - Requested API method doesn't exist

429 Rate limit has been exceeded

500, 502, 503, 504 Server errors