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.

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:

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:

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