Geo.ly API

Geo.ly provides an API which allows you to create, get details of and display maps directly from your own websites, scripts or systems.

Geo.ly API calls

Make a map (using a location or address)
Make a map (using latitude and longitude coordinates)
Get map details

We plan to make some additional search API calls available in future.

Important Many of the API calls are rate-limited to 120 requests/hour - if you exceed your limit an error code (503) will be returned instead of the data requested. If you abuse this service by repeatedly exceeding your rate limit, you will be permanently blocked.
The API is subject to change although we will always try to maintain backward compatibility.

1. Make a map (using a location or address)

Makes a map based on the location or address

Example URL:

http://geo.ly/api/make?q=harrods+uk&n=Harrods&i=Great+store&u=www.harrods.com&m=place&t=url

Parameters:

q : (required, see note below) the location or address, eg statue of liberty
c : (optional, default = us) the ccTLD ("top-level domain") 2 character country code
n : (optional) the name for your map
i : (optional) extra information that you want shown with the map
u : (optional) any web page url that you want associated with the map
m : (optional, default = place) the marker to be shown (place, event or meeting)
t : (optional, default = url) what to return from the call (url, xml or json)

Where the address or location exists in more than one country, the US address will be returned by default. In order to specify the preferred country use the c parameter to override this behaviour, or specify the country within the q string.

Return:

The action and data returned by this call is determined by the t parameter. If this parameter is not specified then the call redirects to the map.

url : (default) redirects to the shortened map URL
xml : the map information as XML
json : the map information as JSON

If the request is missing any required parameters then a 400 error is returned.
If the location cannot be geocoded then a 404 error is returned when t=url, otherwise the success flag will be false for any JSON or XML response.

HTTP Method(s):

GET, POST

Notes:

This call is rate limited.
If you issue this call with the same parameters more than once then same map (and hash) will be returned.

Create map examples

This example creates a map of the Statue of Liberty and redirects to the map
http://geo.ly/api/make?q=statue+of+liberty&n=Statue+of+Liberty
This example creates a map of the Eiffel Tower (with its website URL) and redirects to the map
http://geo.ly/api/make?q=eiffel+tower+france&n=Eiffel+Tower&u=http://www.tour-eiffel.fr/teiffel/uk/
This example creates a map of the Eiffel Tower and returns the map data as XML
http://geo.ly/api/make?q=eiffel+tower+france&n=Eiffel+Tower&t=xml

Example of returned data

json format
{'success': true, 'geocode':{'accuracy':9, 'accuracytext':'Premise (building name, property name, shopping center) level', 'address':'Eiffel Tower, Paris, France'}, 'mapurl':'http://geo.ly/b44fx', 'map':{ 'hash':'b44fx', 'location':'eiffel tower', 'name':'Eiffel Tower', 'information':null, 'url':'http://www.tour-eiffel.fr/teiffel/uk/', 'latlng':'48.858205,2.294359', 'created':'2009-04-25T18:17:20+00:00' } }
xml format
<?xml version="1.0" encoding="UTF-8" ?>
<response success="true">
<geocode>
  <accuracy score="9">Premise (building name, property name) level</accuracy>
  <address>Eiffel Tower, Paris, France</address>
</geocode>
<map url="http://geo.ly/5bck">
  <hash>5bck</hash>
  <location><![CDATA[eiffel tower]]></location>
  <name><![CDATA[Eiffel Tower]]></name>
  <information></information>
  <url><![CDATA[http://www.tour-eiffel.fr/teiffel/uk/]]></url>
  <latlng lat="48.858205" lng="2.294359">48.858205,2.294359</latlng>
  <datecreated>2009-04-25T18:24:23+00:00</datecreated>
</map>
</response>

2. Make a map (using latitude and longitude coordinates)

Makes a map using using latitude and longitude (GPS) coordinates

Example URL:

http://geo.ly/api/make?lat=40.6894&lng=-74.0447&n=Statue+of+Liberty&t=url

Parameters:

lat : (required, see note below) the latitude of the marker
lng : (required, see note below) the longitude of the marker
n : (optional) the name for your map
i : (optional) extra information that you want shown with the map
u : (optional) any web page url that you want associated with the map
m : (optional, default = place) the marker to be shown (place, event or meeting)
t : (optional, default = url) what to return from the call (url, xml or json)

The lat and lng parameters must be specified in decimal degrees and not minutes and seconds.

Return:

The action and data returned by this call is determined by the t parameter. If this parameter is not specified then the call redirects to the map.

url : (default) redirects to the shortened map URL
xml : the map information as XML
json : the map information as JSON

If the request is missing any required parameters then a 400 error is returned.

HTTP Method(s):

GET, POST

Notes:

This call is rate limited.
If you issue this call with the same parameters more than once then same map (and hash) will be returned.

Create map examples

This example creates a map of the Statue of Liberty and redirects to the map
http://geo.ly/api/makelat=40.6894&lng=-74.0447&n=Statue+of+Liberty
This example creates a map of the Eiffel Tower and returns the map data as XML
http://geo.ly/api/make?lat=48.8582&lng=2.2944&n=Eiffel+Tower&t=xml

Example of returned data

json format
{'success': true, 'geocode':{'accuracy':0, 'accuracytext':'Unknown', 'address':'48.8582,2.2944'}, 'mapurl':'http://geo.ly/b44fx', 'map':{ 'hash':'b44fx', 'location':'eiffel tower', 'name':'Eiffel Tower', 'information':null, 'url':'http://www.tour-eiffel.fr/teiffel/uk/', 'latlng':'48.858205,2.294359', 'created':'2009-04-25T18:17:20+00:00' } }
xml format
<?xml version="1.0" encoding="UTF-8" ?>
<response success="true">
<geocode>
  <accuracy score="0">Unknown</accuracy>
  <address>48.8582,2.2944</address>
</geocode>
<map url="http://geo.ly/5bck">
  <hash>5bck</hash>
  <location><![CDATA[eiffel tower]]></location>
  <name><![CDATA[Eiffel Tower]]></name>
  <information></information>
  <url><![CDATA[http://www.tour-eiffel.fr/teiffel/uk/]]></url>
  <latlng lat="48.858205" lng="2.294359">48.858205,2.294359</latlng>
  <datecreated>2009-04-25T18:24:23+00:00</datecreated>
</map>
</response>

3. Get map details

Gets details of a map - this is useful for getting map details before or instead of displaying the map. Maps are specified using their hash identifier.

Example URL:

http://geo.ly/api/get?h=5bbfx&t=json

Parameters:

h : (required) hash identifier for the map
t : (optional, default = xml) what to return from the call (xml or json)

Return:

The map data as either XML or json.

xml : (default) the map information as XML
json : the map information as JSON

HTTP Method(s):

GET, POST

Notes:

This call is rate limited.

Get map examples

This example gets the details of the map identified by the hash b44fx and returns the data in json format
http://geo.ly/api/get?h=b44fx&t=json

Example of returned data

json format
{'success': true, 'mapurl':'http://geo.ly/b44fx', 'map':{ 'hash':'b44fx', 'location':'eiffel tower', 'name':'Eiffel Tower', 'information':null, 'url':'http://www.tour-eiffel.fr/teiffel/uk/', 'latlng':'48.858205,2.294359', 'created':'2009-04-25T18:17:20+00:00' } }
xml format
<?xml version="1.0" encoding="UTF-8" ?>
<response success="true">
<map url="http://geo.ly/5bck">
  <hash>5bck</hash>
  <location><![CDATA[eiffel tower]]></location>
  <name><![CDATA[Eiffel Tower]]></name>
  <information></information>
  <url><![CDATA[http://www.tour-eiffel.fr/teiffel/uk/]]></url>
  <latlng lat="48.858205" lng="2.294359">48.858205,2.294359</latlng>
  <datecreated>2009-04-25T18:24:23+00:00</datecreated>
</map>
</response>