From the beginning, hereit.is was built with the provision of an easy-to-use RESTful API in mind. That said, the interface is still a work in progress: the service may respond to HTTP requests in an incomplete or incorrect manner. Please use Get Satisfaction to report any problems or discuss any ideas you might have about improving the API, and I'll try my best to implement them.
Placemark resources (locations stored in the hereit.is database with specific urls) are currently available in three formats: HTML, JSON (specifically, GeoJSON) and XML (specifically, KML). HTML is the default; alternative representations can be retrieved by appending the required format to the url when making a GET request.
“GeoJSON is a format for encoding a variety of geographic data structures. A GeoJSON object may represent a geometry, a feature, or a collection of features.”
To retrieve a GeoJSON representation of a placemark, send a GET request to:
For more information, see http://geojson.org
“Keyhole Markup Language (KML) is an XML-based language schema for expressing geographic annotation and visualization on existing or future Web-based, two-dimensional maps and three-dimensional Earth browsers.”
To retrieve a KML representation of a placemark, send a GET request to:
For more information, see http://code.google.com/apis/kml/documentation/
hereit.is does not currently support the use of the HTTP
Accept header to request alternative resource representations. This feature may be added in the future.
Placemarks may be created by sending a POST request to http://hereit.is containing a simple form-encoded representation of a placemark. The fields in the request are as follows:
The location of the placemark north or south of the equator, in decimal degrees.
For example: 50.819716.
The location of the placemark east or west of the prime meridian, in decimal degrees.
For example: -0.136572.
This corresponds to Google Maps API zoom level setting.
“Zoom levels between 0 (the lowest zoom level, in which the entire world can be seen on one map) to 19 (the highest zoom level, down to individual buildings) are possible within the normal maps view. Zoom levels vary depending on where in the world you're looking, as data in some parts of the globe is more defined than in others.”
See the Google Maps API documentation for more information.
If the zoom level is not provided in the POSTed data, it will default to zero. Note that not all zoom levels may be available for every part of the world through the Google Maps API service.
The desired url path at which to create this location.
For example, 'brighton' would create a placemark at http://hereit.is/brighton
If the slug is not provided in the POSTed data, or is set to an empty string, a slug will be generated for you automatically.
This text will appear in a ‘bubble’ pointing at the location you create. See http://hereit.is/brighton for an example of how this will look.
The response you receive from your POST request will contain an HTTP response code which will inform your application about the status of the request. Possible response codes are as follows:
Your request was successful. In this case, the response will also contain a
Location header which informs you of the url of your new placemark resource.
Your request failed because the slug you requested is already taken.
400 Bad Request
This code can indicate several types of failure:
500 Internal Server Error
Something went wrong while the server was attempting to process your request. If this happens, please let me know on Get Satisfaction.
If you are using a UNIX-based operating system (such as Mac OS X or a variant of GNU/Linux) it is likely that you already have a copy of the command-line tool cURL (if not, you can download it and install it yourself, or get it from your package repository).
Among other things, cURL allows you to make HTTP requests from a terminal, and so can be used to create and view placemark resources on hereit.is.
NOTE: all the examples supplied below should be entered as a single line, even if they appear to wrap in your browser
By default, cURL will perform a GET request when supplied with a url. So, to retrieve a JSON representation of a location (here, I'm using ‘brighton’ as an example), type the following command into a terminal:
Similarly, to retrieve a KML representation, type:
You can then parse these representations to extract the information you need.
cURL can also be used to send POST requests. To do this, simply add the switch
-d followed by a form-encoded representation of your location (this is just a set of
key=value pairs separated by ampersands).
As you will mostly be interacting with the service using HTTP headers, you can use the
-i switch to show both the headers and the body of the response.
First, let's try creating a placemark that we know already exists:
curl -i -d 'latitude=50.819716&longitude=-0.136572&zoom=5&slug=brighton' http://hereit.is
You will see the HTML of the response printed to your terminal. If you scroll up, above this you will see the headers that were included with the response. The first of these should be
HTTP/1.1 409 Conflict, indicating that the slug you requested is already taken.
Now, we'll create the same location, but allow hereit.is to generate a slug for us. Simply omit the ‘slug’ field from the POSTed data:
curl -i -d 'latitude=50.819716&longitude=-0.136572&zoom=5' http://hereit.is
Again, you will see the HTML of the response body, with the headers above it. This time, the first line will be
HTTP/1.1 201 Created, indicating that your request was successful. Additionally, you will see the header
Location: http://hereit.is/2i, informing you of the url of your new resource (of course, the slug would be different if you were to try this yourself).
The information in this document should provide you with everything you need to interact with the hereit.is REST API. If you have any problems, questions or suggestions, please report them at Get Satisfaction and I'll try to respond as quickly as I can. I'd also be really interested in hearing about how you are using the API in your own applications.
Last updated: Sunday 19th July 2009