World class geocoding

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.

placeId:

string Optional - this feature is only available in custom packages. Will be a unique ID for this address, if the address could be found with sufficient accuracy. This ID is 22 characters long.

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'

languages:

string Languages spoken in the country, by number of speakers (most common first). Each language can be in the form 'en' or 'en-US'. The first part is the ISO-639 language abbreviation and the optional second part is the ISO-3166 country code.

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"
  },
  "placeId": "YiiZekJ6Y3sCB5f6-yhApO"
}

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'. Optionally send in 'detect', to use the IP address of the client that is placing the API request.


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"
  }
}

Phone Geocoding

To geocode a phone number, send in the phone querystring parameter, preferably in E.164 format. You can also send in the associated country code (e.g. 'US') if this is known. If you send in a phone number in another format that doesn't include a country code, the number will be expected to be from the US unless another country is specified.

Phone number geocoding has a much more limited accuracy than address geocoding. Typically, phone numbers geolocations will only be precise down to a city or even a country.

Request parameters

phone:

string Phone number, preferably in the E.164 format: +11234567890. Optionally in a local format, such as 123-456-7890. If a format is used without a country code and the phone number is not from the US, specify the country code field.

country:

string Optional. The textual country code in ISO-3166-1 alpha-2 format, e.g. US or CA. This is not a numerical phone number country code!


https://api.geolake.com/geocode?api_key=XYZ&phone=415-701-0000&country=US

# Object Response
{
   "success": true,
   "latitude": 37.760741,
   "longitude": -122.436785,
   "accuracyType": "city",
   "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