Geograph

Geograph API v0.81

Geograph's Application Programming Interface (API) allows third party developers to create applications using data sourced from Geograph, in a friendly and polite way.

Chances are you have come to this page because you are a developer looking to get access to some of the data, well you've come to the right place, below you will find brief details of what's available and how to get it...

Please note that the API is still in its early stages, these are the possiblities that the developers needed, or felt would be useful, if you have any special requests then don't be shy, just let us know.

	Subscribe to Geograph-API-Users
	Email:
Recommended, API updates will be posted here. Low traffic, membership list is not disclosed.

Each of these Feeds includes the photographer credit/name, which under the CC licence MUST be displayed along any use of the image. Also the fact the image is CC licenced needs to be mentioned.

Ideally also you could link back to the main photo page, either with the link supplied or with http://geo.hlipp.de/photo/[id].

Thank you for your attention in this matter.

Torrents - Bulk Image download

The entire (or at least it will be) archive is available for download via bittorrent - see http://torrents.geograph.org.uk for details.

API-key

If you haven't got one you will need to obtain a unique API-key, which gives you access to the pages below, simply contact us, with a brief outline of your project, please include the URL so we can take a look.

Once you have a API-key simply replace [apikey] in the examples below to obtain your feed.

RSS-feeds RSS

Really Simple Syndication allows you to obtain a details for a number of images, (usually) in XML format, this makes it really easy for you to reuse small section of information on your website or project. The feed lives at

http://geo.hlipp.de/syndicator.php?key=[apikey]

and by default returns obtains an up-to-date listing of the 20 latest geograph submissions, you can however return different results as below

Feed Type

You should supply one of the following parameters to specify the type of results you would like...

Options

Formats

There is a number of standard formats the feed is available in

format=RSS0.91	RSS 0.91
format=RSS1.0	RSS 1.0
format=RSS2.0	RSS 2.0
format=GeoRSS	GeoRSS - Default - Extension of RSS 1.0 to include the lat/long, see georss.org
format=GeoPhotoRSS	GeoPhotoRSS - Further custom extension of GeoRSS to also include the thumbnail url, see pheed.com
format=GPX	GPX 1.0 - the GPS Exchange Format, see topografix.com
format=OPML	OPML
format=HTML	HTML - ideal to be output by a server side script or to be included in an IFRAME
format=JS	JavaScript - ideal to output a simple table with a single <SCRIPT> tag
	<script src="http://geo.hlipp.de/syndicator.php?key=[apikey]&format=JS" type="text/javascript"></script>
format=PHP	PHP - returns a valid php page, that builds a data-structure for use via include. (includes the thumbnail url)
format=KML	KML - suitable for use directly in Google Earth (XML based - includes the thumb url and lat/long!) accepts additonal paramaters: simple=1 If present includes styling to hide the picture label unless hovering over the photo (recommended!)

REST interface

Provides a very simple interface for obtaining details about a particular image or grid square. Will later be extended to include contributors, and tags, and possibly even hectads and myriads and some aggregate statistics. If looking for bulk downloads please consider one of the alternative means.

Services

<?xml version="1.0" encoding="UTF-8" ?> 
<geograph>
  <status state="ok" /> 
  <title>Bascote</title> 
  <gridref>SP4063</gridref> 
  <user profile="http://geo.hlipp.de/profile/120">David Stowell</user> 
  <img src="http://geo.hlipp.de/photos/00/34/003456_e10e23bc.jpg"
     width="640" height="480" /> 
</geograph>

<?xml version="1.0" encoding="UTF-8" ?> 
<geograph>
  <status state="ok" count="1" /> 
  <image url="http://geo.hlipp.de/photo/64854">
    <title>Afon Cynfal</title> 
    <user profile="http://geo.hlipp.de/profile/3">Barry Hunter</user> 
    <img src="http://geo.hlipp.de/photos/06/48/064854_d68e7342_120x120.jpg" width="90" height="120" /> 
    <location grid="1" eastings="270500" northings="341100" /> 
  </image>
</geograph>

CSV Export

Note, that these CSV exports have become very inefficient, and so will only return 1000 records without prior arrangement.

This is ideal for bulk downloads, or for keeping an offsite cache up-to-date, it lives at:

http://geo.hlipp.de/export.csv.php?key=[apikey]

but works best in combination with the parameters below.

Parameters

* because these results also return images modified within the period its possible you will receive updates to images you already have. You can safely use the ID column to check for duplicates. the modified date is changed when anything about the image changes, for example of the title or comment, its possible you will get a row that nothing has apparentlly changed, but these should be very few.

Columns

Returning Extra Columns

NOTE: You can only supply EITHER en OR ll, not both

Building a Search Query

There are there main methods for obtaining some valid i numbers for passing to the RSS or CSV feeds (or in fact directing the user to a search results page!).

TIP: where ever you pass a i parameter you can also pass a page parameter to return another page of results. eg http://geo.hlipp.de/syndicator.php?key=[apikey]&i=12345&page=2

Places to use an i number

Each one accepts the Page paramater, to get the next page of results.

Other Ways to download information

• MemoryMap Exports
• GPX Exports
• 100x100km CheckSheets (example) - nice easy parseable listing, could be used for creating coverage maps
• Please DON'T use the /list/ namespace as that's for Search Engines
• sitemap.xml - see http://www.sitemaps.org
• geourl.org (Coming soon)
• We can also create coverage csv's on demand, (listing squares currently with images)

Finally

We wish you luck in you project and look forward to seeing the results! If you have any problems using the API, then please do get in contact, or join the Geograph-API-Users Google Discussion Group.