Introduction

Welcome to the Geloky API! You can use our Geocoding API to geocode or reverse geocode your data. It allows you to convert addresses to latitude and longitude or convert latitude and longitude to addresses in two formats. There are Geloky and Google Maps response formats.

You can view code examples in the dark area to the right.

Authentication

Geloky uses API keys to allow access to the API. It’s easy to get. Just visit your dashboard panel and you will find your API key there. You can easily replace the API key there too.

Geloky expects for the API key to be included in all API requests to the server as a GET parameter.

Geocoding API

Overview

What is geocoding?

Geocoding is the process of converting addresses (like "1600 Amphitheatre Parkway, Mountain View, CA") into geographic coordinates (like latitude 37.423021 and longitude -122.083739).

Reverse geocoding is the process of converting geographic coordinates into a human-readable address.

The Geocoding API provides a direct way to access these services via an HTTP request. You can check data accuracy the Geocoding service returns here and here.

Geocoding API requests and responses

GET https://geloky.com/api/geo/geocode?address=350, 5th Avenue, New York, 10018, United States&key=YOUR_API_KEY&format=geloky

The above command returns JSON structured like this:

[
  {
    "address": "350 5th Ave, New York, New York, 10118",
    "latitude": 40.74837686528841,
    "longitude": -73.98485413472395
  }
]

GET https://geloky.com/api/geo/geocode?address=350, 5th Avenue, New York, 10018, United States&key=YOUR_API_KEY&format=google

The above command returns JSON structured like this:

{
  "results": 
  [
    {
      "formatted_address": "350 5th Ave, New York, New York, 10118",
      "geometry": 
      {
        "location": 
        {
          "lat": 40.74837686528841,
          "lng": -73.98485413472395
        }
      }
    }
  ],
  "status": "OK"
  }

A Geocoding API request takes the following form: GET https://geloky.com/api/geo/geocode?parameters

Query Parameters

Parameter	Required	Default	Description
address	Yes		The street address that you want to geocode. Specify addresses in accordance with the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers should be avoided. Street address elements should be delimited by spaces (shown here as url-escaped to %20): `address=24%20Sussex%20Drive%20Ottawa%20ON`
key	Yes		Your application's API key. This key identifies your application for purposes of quota management. You can get a key here
format	No	geloky	Structure format of returned data. It can be geloky or google

Reverse geocoding (address lookup) request and response

GET https://geloky.com/api/geo/reverse-geocode?latlng=40.74837686528841,-73.98485413472395&key=YOUR_API_KEY&format=geloky

The above command returns JSON structured like this:

[
  {
    "address": "Empire State Building, 350, 5th Avenue, Koreatown, Manhattan, New York County, New York, 10018, United States",
    "latitude": 40.74837686528841,
    "longitude": -73.98485413472395
  }
]

GET https://geloky.com/api/geo/reverse-geocode?latlng=40.74837686528841,-73.98485413472395&key=YOUR_API_KEY&format=google

The above command returns JSON structured like this:

{
  "results": 
  [
    {
      "formatted_address": "Empire State Building, 350, 5th Avenue, Koreatown, Manhattan, New York County, New York, 10018, United States",
      "geometry": 
      {
        "location": 
        {
          "lat": 40.74837686528841,
          "lng": -73.98485413472395
        }
      }
    }
  ],
  "status": "OK"
}

The term geocoding generally refers to translating a human-readable address into a location on a map. The process of doing the opposite, translating a location on the map into a human-readable address, is known as reverse geocoding

A Reverse Geocoding API request takes the following form: GET https://geloky.com/api/geo/reverse-geocode?parameters

Query Parameters

Parameter	Required	Default	Description
latlng	Yes		The latitude and longitude values specifying the location for which you wish to obtain the closest, human-readable address.
key	Yes		Your application's API key. This key identifies your application for purposes of quota management. You can get a key here
format	No	geloky	Structure format of returned data. It can be geloky or google

Batch Geocoding API requests and responses

GET https://geloky.com/api/geo/geocode-batch?addresses=["350, 5th Avenue, New York, 10018, United States", "Volodymirska, 40A, Kyiv, 01034, Ukraine"]&key=YOUR_API_KEY&format=geloky

The above command returns JSON structured like this:

[
  {
    "address": "350 5th Ave, New York, New York, 10118",
    "latitude": 40.74837686528841,
    "longitude": -73.98485413472395
  },
  {
    "address": "Volodymyrska vulytsia 40A, Shevchenkivskyi raion, Kyiv",
    "latitude": 50.449698631481176,
    "longitude": 30.514730616759174
  }
]

GET https://geloky.com/api/geo/geocode-batch?addresses=["350, 5th Avenue, New York, 10018, United States", "Volodymirska, 40A, Kyiv, 01034, Ukraine"]&key=YOUR_API_KEY&format=google

The above command returns JSON structured like this:

{
  "results": [
    {
      "formatted_address": "350 5th Ave, New York, New York, 10118",
      "geometry": 
      {
        "location": 
        {
          "lat": 40.74837686528841,
          "lng": -73.98485413472395
        }
      }
    },
    {
      "formatted_address": "Volodymyrska vulytsia 40A, Shevchenkivskyi raion, Kyiv",
      "geometry": 
      {
        "location": 
        {
          "lat": 50.449698631481176,
          "lng": 30.514730616759174
        }
      }
    }
  ],
  "status": "OK"
}

Batch Geocoding API is a REST API that allows you to geocode large data sets. You can geocode a lot of addresses at once, as minimum - starting from one address and ending with as many needed.

A Batch Geocoding API request takes the following form: GET https://geloky.com/api/geo/geocode-batch?parameters

Query Parameters

Parameter	Required	Default	Description
addresses	Yes		An array of street addresses that you want to geocode. Specify addresses in accordance with the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers should be avoided. Street address elements should be delimited by spaces. Addresses should be specified in an array and delimited by comma.
key	Yes		Your application's API key. This key identifies your application for purposes of quota management. You can get a key here.
format	No	geloky	Structure format of returned data. It can be geloky or google

Batch Reverse Geocoding API requests and responses

GET https://geloky.com/api/geo/reverse-geocode-batch?coordinates=["40.748428399999995,-73.98565461987332","50.43347000000006,30.51968000000005"]&key=YOUR_API_KEY&format=geloky

The above command returns JSON structured like this:

[
  {
    "address": "Empire State Building, 350, 5th Avenue, Koreatown, Manhattan, New York County, New York, 10018, United States",
    "latitude": 40.748428399999995,
    "longitude": -73.98565461987332
  },
  {
    "address": "Музей спортивної слави України, Велика Васильківська вулиця 55, Печерський район, Київ",
    "latitude": 50.43347000000006,
    "longitude": 30.51968000000005
  }
]

GET https://geloky.com/api/geo/reverse-geocode-batch?coordinates=["40.748428399999995,-73.98565461987332","50.43347000000006,30.51968000000005"]&key=YOUR_API_KEY&format=google

The above command returns JSON structured like this:

{
  "results": [
    {
      "formatted_address": "Empire State Building, 350, 5th Avenue, Koreatown, Manhattan, New York County, New York, 10018, United States",
      "geometry": 
      {
        "location": 
        {
          "lat": 40.748428399999995,
          "lng": -73.98565461987332
        }
      }
      },
        {
      "formatted_address": "Velyka Vasylkivska street 55, Pechersky district, Kyiv, Ukraine",
      "geometry": 
      {
        "location": 
        {
          "lat": 50.43347000000006,
          "lng": 30.51968000000005
        }
      }
    }
  ],
  "status": "OK"
}

Reverse geocode large data sets in one request. The process of translating a location on the map into a human-readable address, is known as reverse geocoding.

A Batch Reverse Geocoding API request takes the following form: GET https://geloky.com/api/geo/reverse-geocode-batch?parameters

Query Parameters

Parameter	Required	Default	Description
coordinates	Yes		An array of coordinates (latitude and longitude values specifying the location for which you wish to obtain the closest, human-readable address). Latitude and Longitude should be delimited by comma. They should be specified in an array and delimited by comma.
key	Yes		Your application's API key. This key identifies your application for purposes of quota management. You can get a key here.
format	No	geloky	Structure format of returned data. It can be geloky or google

Distance Matrix/Routing API

Overview

Distance Matrix service computes travel distance and journey duration between multiple origins and destinations using a given mode of travel. The distance endpoint returns totals only; the multi-stop route endpoint below also returns each leg and the route geometry. As simple as it may seem, it’s an extraordinarily powerful tool that finds utility across a spectrum of industries and use cases.

The Distance Matrix/Routing API provides a direct way to access this service via an HTTP request.

Distance Matrix/Routing API requests and responses

GET https://geloky.com/api/geo/distance?origin=52.429892,13.505498&destination=52.522199,13.425576&key=YOUR_API_KEY&format=geloky

The above command returns JSON structured like this:

[
  {
    "origin": "52.429892,13.505498",
    "destination": "52.522199,13.425576",
    "length": 11.097,
    "time": 27.54
  }
]

GET https://geloky.com/api/geo/distance?origin=52.429892,13.505498&destination=52.522199,13.425576&units=km&vehicle=walk&key=YOUR_API_KEY&format=google

{
  "destination": "52.522199,13.425576",
  "origin": "52.429892,13.505498",
  "rows": 
  [
    {
      "elements": {
        "distance": 
        {
          "text": "13.498 km",
          "value": 13.498
        },
        "duration": 
        {
          "text": "161.97 mins",
          "value": 161.97
        },
        "status": "OK"
      }
    }
  ],
  "status": "OK"
}

Distance Matrix/Routing API provides travel distance and time for a matrix of origin and destination.

A Distance Matrix/Routing API request takes the following form: GET https://geloky.com/api/geo/distance?parameters

Query Parameters

Parameter	Required	Default	Description
origin	Yes		Starting point for calculating travel distance and time. Location in the form of latitude/longitude coordinates or longitude/latitude coordinates
destination	Yes		One location to use as the final destination for calculating travel distance and time. Location in the form of latitude/longitude coordinates or longitude/latitude coordinates
order	No	lat_lon	You may specify an order of what stands first in origin and destination. lat_lon stands for Latitude/Longitude. lon_lat stands for Longitude/Latitude
priority	No	fast	You may specify a priority of your route. It can be the fastest route or the shortest route.
vehicle	No	auto	For the calculation of distances, you may specify the transportation mode to use. By default, distances are calculated for the driving mode. The following travel modes are supported: auto, walk, truck
units	No	ml	You can specify units for distance. It can be miles or kilometers. Default units are miles. The following units are supported: ml, km
key	Yes		Your application's API key. This key identifies your application for purposes of quota management. You can get a key here.
format	No	geloky	Structure format of returned data. It can be geloky or google

Multi-stop Route API requests and responses

GET https://geloky.com/api/geo/route?points=40.7128,-74.0060|39.9526,-75.1652|38.9072,-77.0369&geometry=geojson&key=YOUR_API_KEY

The above command routes New York to Philadelphia to Washington, DC and returns JSON structured like this (distances in miles, the default; the coordinates list is shortened here, a real response contains the full route shape):

{
  "legs": [
    {
      "origin": "40.7128,-74.0060",
      "destination": "39.9526,-75.1652",
      "length": 94.423,
      "time": 125.55
    },
    {
      "origin": "39.9526,-75.1652",
      "destination": "38.9072,-77.0369",
      "length": 137.355,
      "time": 187.74
    }
  ],
  "total": {
    "length": 231.778,
    "time": 313.29
  },
  "geometry": {
    "type": "LineString",
    "coordinates": [[-74.006257, 40.712508], [-74.006347, 40.712553], [-74.006583, 40.712665], ...]
  },
  "source": "routing"
}

GET https://geloky.com/api/geo/route?points=40.7128,-74.0060|39.9526,-75.1652|38.9072,-77.0369&units=km&geometry=polyline&key=YOUR_API_KEY

The same route in kilometers, with the shape as a Google encoded polyline string:

{
  "legs": [
    {
      "origin": "40.7128,-74.0060",
      "destination": "39.9526,-75.1652",
      "length": 151.959,
      "time": 125.55
    },
    {
      "origin": "39.9526,-75.1652",
      "destination": "38.9072,-77.0369",
      "length": 221.052,
      "time": 187.74
    }
  ],
  "total": {
    "length": 373.011,
    "time": 313.29
  },
  "geometry": "etnwFbjubMGPWl@AD?@o@`BCDADC@IDC?ABIVaCpGGRKGmA}...",
  "source": "routing"
}

A request that cannot be served returns an error object instead of legs, and nothing is charged:

{
  "code": "ERROR",
  "message": "points may contain at most 25 locations"
}

The Multi-stop Route API calculates the road route through two or more points, visited in the order given, and returns one leg per consecutive pair of points (A to B, B to C, and so on) with the travel distance and time of each leg, the total for the whole route, and optionally the route geometry to draw on a map. All points are routed in one go, so the legs join up into a single continuous route and the total is exactly the sum of the legs.

A Multi-stop Route API request takes the following form: GET https://geloky.com/api/geo/route?parameters

Pricing: every leg is billed as one API request, so a route through N points costs N-1 requests. A route through 3 points has 2 legs and costs 2 requests. Requests that return an error are not charged. See API pricing.

Query Parameters

Parameter	Required	Default	Description
points	Yes		Two to 25 locations separated by `\|`, visited in the order given. Each location is a latitude,longitude pair (or longitude,latitude with `order=lon_lat`). A JSON array of such strings is accepted as well.
order	No	lat_lon	The coordinate order used in points, and in the origin and destination fields of the response. lat_lon stands for Latitude/Longitude. lon_lat stands for Longitude/Latitude
priority	No	fast	You may specify a priority of your route. It can be the fastest route (fast) or the shortest route (short).
vehicle	No	auto	The transportation mode: auto, walk or truck. Use direct to get straight-line (great-circle) distances between consecutive points instead of a road route; direct legs have no travel time.
units	No	ml	Units for distances: ml (miles) or km (kilometers). Times are always in minutes.
geometry	No	none	Whether to include the route shape: none, geojson (a GeoJSON LineString with [longitude, latitude] coordinates) or polyline (a Google encoded polyline with 5 decimal places). The shape covers the whole route from the first point to the last.
key	Yes		Your application's API key. This key identifies your application for purposes of quota management. You can get a key here.

Response fields

Field	Description
legs	One object per consecutive pair of points, in route order: origin and destination (the points as you sent them), length (in the requested units) and time (minutes; "-" for vehicle=direct).
total	The length and time of the whole route, equal to the sum of the legs.
geometry	The route shape in the requested format, or null when geometry=none.
source	routing for a road route, direct for straight-line distances.
code, message	Present instead of the fields above when the request could not be served: code is ERROR and message says why. Such requests are not charged.