here it .is

API Documentation

Introduction

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 Representations

Overview

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.

• HTML

  HTML is the default representation available for a location. If you visit, for example, http://hereit.is/brighton with your browser, you will receive an HTML page which renders a simple embedded Google map of the location, along with a link to the corresponding Google Maps page.

• GeoJSON

  “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:

  http://hereit.is/<your slug>.json

  For more information, see http://geojson.org

• KML

  “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:

  http://hereit.is/<your slug>.kml

  For more information, see http://code.google.com/apis/kml/documentation/

Content Negotiation

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.

Creating Placemarks

Overview

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:

• latitude (required)

  The location of the placemark north or south of the equator, in decimal degrees.

  For example: 50.819716.

• longitude (required)

  The location of the placemark east or west of the prime meridian, in decimal degrees.

  For example: -0.136572.

• zoom (optional, recommended)

  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.

• slug (optional)

  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.

• bubble (optional)

  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.

Response codes

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:

• 201 Created

  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.

• 409 Conflict

  Your request failed because the slug you requested is already taken.

• 400 Bad Request

  This code can indicate several types of failure:

  • Your requested slug contained invalid characters. Slugs can only consist of letters, numbers and underscores. In this case, the response body will contain a form which is pre-populated with a suggested alternative slug, in which all the illegal characters have been replaced with underscores.
  • Your request was invalid in some other way. For example, you must supply at least latitude and longitude in the request for it to be successful. Also, the latitude, longitude and zoom you supplied must be numeric data. In this case, the response body will contain information about the reason your request failed.

• 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.

Examples

Overview

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

Retrieving placemark representations

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:

curl http://hereit.is/brighton.json

Similarly, to retrieve a KML representation, type:

curl http://hereit.is/brighton.kml

You can then parse these representations to extract the information you need.

Creating placemarks

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).

Conclusion

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