Geograph - photograph every grid square

Geograph API Documentation _{(last updated 1st May 2012)}

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 possibilities that the developers needed, or felt would be useful, if you have any special requests then don't be shy, just let us know.

· Looking for Inspiration? The Links Directory has a listing of API powered websites.

All exports include the photographer credit/name, which under the CC licence MUST be displayed alongside 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 https://www.geograph.org.uk/photo/[id].

Thank you for your attention in this matter.

Database Dumps - Bulk Data download

We have created a mysqldump snapshot of the database and made it available for download, see data.geograph.org.uk/dumps 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 feeds below, simply request a key, 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.

Images API

This API accesses the Images database, allowing a wide variety of output formats, and filtering options. Include RSS style outputs (can be used directly as a RSS feed), but also supports various XML, KML, JSON and HTML outputs. The feed lives at

https://api.geograph.org.uk/syndicator.php?key=[apikey]

and by default returns obtains an up-to-date listing of the 15 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

The feed is available in a number of standard formats:

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="https://api.geograph.org.uk/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 additional parameters: simple=1 If present includes styling to hide the picture label unless hovering over the photo (recommended if using with Google Earth!)
format=JSON NEW!	JSON encoded output - particully suitable for integration into Javascript apps, but many other languages have json decoders. Also supports JSONP with &callback=functionname so can use in a webapp - JQuery etc make this easy!

Details API

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="https://www.geograph.org.uk/profile/120">David Stowell</user> 
  <img src="https://www.geograph.org.uk/photos/00/34/003456_e10e23bc.jpg" crossorigin="anonymous" width="640" height="480" style="image-orientation:none"/> 
</geograph>

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

<?xml version="1.0" encoding="UTF-8" ?> 
<geograph>
  <status state="ok" count="1" total="1034"/> 
  <image url="https://www.geograph.org.uk/photo/1575413"> 
    <title>St Nicholas Hall</title>
    <user profile="https://www.geograph.org.uk/profile/17441">David Lally</user> 
    <img src="https://www.geograph.org.uk/geophotos/01/57/54/1575413_be18cb70_120x120.jpg" width="120" height="90" />
    <location grid="1" lat="50.642106" long="-1.950011"/> 
  </image>
</geograph>

Formats

The feed is available in a number of standard formats:

CSV Export

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

Please consider Database Dumps instead.

More suited for bulk downloads, or for keeping an offsite cache up-to-date, it lives at:

https://api.geograph.org.uk/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 it's 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, it's possible you will get a row that nothing has apparently changed, but these should be very few.

Columns

Returning Extra Columns

NOTE: The "en" and/or "ppos" options can't be used at same time as "ll" and/or "tags"

Building a Search Query

There are three 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 https://api.geograph.org.uk/syndicator.php?key=[apikey]&i=12345&page=2

Places to use an i number

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

Other Ways to download information

• GPX Exports
• 100x100km CheckSheets (example) - nice easy parsable listing, could be used for creating coverage maps
• sitemap.xml - see http://www.sitemaps.org
• geourl.org (Coming soon)
• We can also create coverage CSVs on demand, (listing squares currently with images)
• data.geograph.org.uk/dumps
  
  
• Please DON'T use the /list/ and/or /sitemap/ namespace as they are to help Search Engines crawlers.

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.