Geograph API Documentation (last updated 1st May 2012)

Please Note: This page is not complete. We have many other APIs available, that we havn't got round to documenting. There is a prototype explorer interface here: http://data.geograph.org.uk/api-doc/, it mentions more of the APIs, but is still missing lots of detail.

If you are looking for a API for specific purpose, please contact us. We probably have one! If not can build it. We would much perfer to work with you to find a suitable API, than forcing you to scrape, or spider the website. Spidering sucks.
Contents

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.

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


Modify 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 http://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/dumpsExternal link for details.

Torrents - Bulk Image download

The entire (or at least it will be) archive is available for download via bittorrent, see torrents.geograph.org.ukExternal link 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 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.

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

http://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

Note: These feeds are designed for ondemand access of specific content, eg finding nearby images for a single page. Not for bulk download of content. Most searches created via this system can only access the first 1,000 images matching the query. For larger extracts, the database dumps are still the best method.

Feed Type

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

-none- 15 latest Geograph submissions
http://api.geograph.org.uk/syndicator.php?key=[apikey]
i=[searchid] runs a predefined search, see Building a Search Query for more information on how to obtain a valid i number. Accepts additional parameter:
page=[number] return a specific page of results
http://api.geograph.org.uk/syndicator.php?key=[apikey]&i=12345
u=[user_id] Limit results to particular user
http://api.geograph.org.uk/syndicator.php?key=[apikey]&u=3
q=[query] Tries to deduce the type of search, either a text or a location search. Can use the format q={what}+near+{where} to be sure (or use separate params as below) - Will in fact create an i query on the fly, so you can use that to get page 2 etc of the results. Accepts additional parameter:
u=[user_id] Limit results to particular user
distance=[number] Limit results to within this distance (in km, default 10km, maximum 20km)
perpage=[number] Number of results per page (15 default, 100 maximum)
http://api.geograph.org.uk/syndicator.php?key=[apikey]&q=bridge+near+TQ7054
location=[location] Returns 15 or all within 10km (which ever is less) of the specified location (grid reference, postcode or decimal lat/long) (see also Building a query for pitfalls of the q parameter) - will in fact create an i query on the fly, so you can use that to get page 2 etc of the results. Accepts additional parameter:
text=[text string] Returns only images matching this text search
u=[user_id] Limit results to particular user
distance=[number] Limit results to within this distance (in km, default 10km, maximum 20km)
perpage=[number] Number of results per page (15 default, 100 maximum)
http://api.geograph.org.uk/syndicator.php?key=[apikey]&location=TQ7054
text=[text string] Returns 15 results matching the word search - will in fact create an i query on the fly, so you can use that to get page 2 etc of the results. Accepts additional parameter:
u=[user_id] Limit results to particular user
perpage=[number] Number of results per page (15 default, 100 maximum)
http://api.geograph.org.uk/syndicator.php?key=[apikey]&text=bridge
callback=[function] wraps the output in a function call. Only works with format=JSON, to allow use in client-side Javascript web-apps
http://api.geograph.org.uk/syndicator.php?key=[apikey]&format=JSON&callback=function

Options

expand=1 If present includes the thumbnail of the image in the description as html (not applicable to KML format).
http://api.geograph.org.uk/syndicator.php?key=[apikey]&expand=1

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.orgExternal link
format=GeoPhotoRSS GeoPhotoRSS - Further custom extension of GeoRSS to also include the thumbnail url, see pheed.comExternal link
format=GPX GPX 1.0 - the GPS Exchange Format, see topografix.comExternal link
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://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

http://api.geograph.org.uk/api/photo/[photo-id]/[apikey]
Photo Details Returns an XML infoset about the particular photograph, currently returns:
<?xml version="1.0" encoding="UTF-8" ?> 
<geograph>
  <status state="ok" /> 
  <title>Bascote</title> 
  <gridref>SP4063</gridref> 
  <user profile="http://www.geograph.org.uk/profile/120">David Stowell</user> 
  <img src="http://www.geograph.org.uk/photos/00/34/003456_e10e23bc.jpg"
     width="640" height="480" /> 
</geograph>
http://api.geograph.org.uk/api/Gridref/[4fig gridref]/[apikey]
Grid Square Details Returns an XML infoset about the particular square, currently returns:
<?xml version="1.0" encoding="UTF-8" ?> 
<geograph>
  <status state="ok" count="1" /> 
  <image url="http://www.geograph.org.uk/photo/64854">
    <title>Afon Cynfal</title> 
    <user profile="http://www.geograph.org.uk/profile/3">Barry Hunter</user> 
    <img src="http://www.geograph.org.uk/photos/06/48/064854_d68e7342_120x120.jpg" width="90" height="120" /> 
    <location grid="1" eastings="270500" northings="341100" /> 
  </image>
</geograph>
http://api.geograph.org.uk/api/latlong/[distance]km/[lat],[long]/[apikey]
Search Nearby [DEPRECATED]
In general, using the syndicator.php API is recommended instead of this option. It offers the same functionality, with a lot more options (eg specifying a sort order, filtering by keywords)

Example: http://api.geograph.org.uk/syndicator.php?format=JSON&q=[lat],[long]&distance=[distance]&key=[apikey]
Returns an XML infoset of surrounding images, currently returns:
<?xml version="1.0" encoding="UTF-8" ?> 
<geograph>
  <status state="ok" count="1" total="1034"/> 
  <image url="http://www.geograph.org.uk/photo/1575413"> 
    <title>St Nicholas Hall</title>
    <user profile="http://www.geograph.org.uk/profile/17441">David Lally</user> 
    <img src="http://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>
Note:the distance should be 10km or below.
http://www.geograph.org.uk/photo/[photo-id].rdf
http://www.geograph.org.uk/photo/[photo-id].kml

Formats

The feed is available in a number of standard formats:

output=xml XML -Default as above
format=json JSON alternative cross-platform format

callback=myFunc wraps the data in a function call - JSONP - useful for cross-domain javascript calls
NOTE: When using in a public web-based project don't use your API key in requests, just use a your domain name as the api key.

CSV Export

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

Please consider Database DumpsExternal link instead.

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

http://api.geograph.org.uk/export.csv.php?key=[apikey]

but works best in combination with the parameters below.

Parameters

-none- returns the whole database, this should only be used for an initial download, then use one of the following methods to just return a subset
http://api.geograph.org.uk/export.csv.php?key=[apikey]
since=[date] Returns all images submitted or modified* on or after this date. Date is in YYYY-MM-DD format.
This is the preferred method, where you simply need to keep track of the day you last checked.
http://api.geograph.org.uk/export.csv.php?key=[apikey]&since=2005-07-01
last=[number]+[interval] Returns all images submitted or modified* during the period specified.
Valid formats for [interval] MINUTE WEEK
HOUR MONTH
DAY YEAR
http://api.geograph.org.uk/export.csv.php?key=[apikey]&last=7+DAY
http://api.geograph.org.uk/export.csv.php?key=[apikey]&last=6+HOUR
limit=[number] Returns the latest [number] images submitted or modified* (also happens to be in descending date order)
http://api.geograph.org.uk/export.csv.php?key=[apikey]&limit=30
ri=[1|2] Limit the results to a particular National Grid
(can be combined with the above parameters)
http://api.geograph.org.uk/export.csv.php?key=[apikey]&ri=1 - Great Britain
http://api.geograph.org.uk/export.csv.php?key=[apikey]&ri=2 - Ireland
i=[searchid] runs a predefined search, see Building a Search Query for more information on how to obtain a valid i number.
NOTE: can't be combined with any of the above parameters, but accepts additional parameters:
count=[number] overrides the page size specified in the query,
or -1 for biggest possible (usually 1000)
page=[number] return a specific page of results
(paginated with the modified 'count')
http://api.geograph.org.uk/export.csv.php?key=[apikey]&i=12345

* 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

Id Unique Numeric ID for the Picture,
to be used to construct the URL to link back to the image
http://www.geograph.org.uk/photo/2345
2345
Name Plain text title for the image Newbury High Street
Grid Ref Four Figure Grid Reference for the image TQ6046 or B5467
Submitter Full name of the submitter of the image, to be used for credit Fred Bloggs
Image Class Plain text image category Village Scene

Returning Extra Columns

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

&taken=1 taken date of the image 2008-07-22
&en=1 add this parameter to add the Eastings, Northings and Precision
http://api.geograph.org.uk/export.csv.php?key=[apikey]&en=1
  Easting Absolute position for the image in m from the Grid False origin. Use the Grid Ref column to deduce with Grid the location refers to. These columns will be 0 when the image isn't positioned with more than a 4 figure grid reference. include &coords=1 to get eastings/northings even for 4 figure references 545667
Northing 234556
Figures 10
&ll=1 add this parameter to return the WGS84 Latitude and Longitude
Lat Position for the image in decimal degrees lat/long, negative longitude is west, specified to as high as accuracy as possible. 53.5564
Long -2.5466
&thumb=1 add this parameter to return the full url to a 120x120 pixel thumbnail
  Thumb URL Example:
http://www.geograph.org.uk/photos/01/76/017622_ed5d17d5_120x120.jpg
&desc=1 include the photo description
&dir=1 view direction in degrees (-1 = undefined) 145
&ppos=1 add this parameter to add the Eastings, Northings and Precision of the Photographer Position
http://api.geograph.org.uk/export.csv.php?key=[apikey]&ppos=1
  Easting Absolute position for the photographer in m from the Grid False origin. Use the Grid Ref column to deduce with Grid the location refers to. These columns will be 0 when the image doesn't include a Photographer Grid Reference 545667
Northing 234556
Figures 10
&submitted=1 Date/Time of image submission
&hits=1 Approximate hit count for the full photo page
&status=1 Moderation status (geograph/accepted)
&level=1 1=First Geograph,2=Second Geograph Contributor Point, etc.
&tags=1 Include the tags as a question mark separated list. Note: can't be used in conjunction with en/ppos options.

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

Predefined Searches Perhaps the simplest way is just to use one of our predefined searches
25654 15 random images, by users joined in the last week
29439 50 recently submitted images
25678 15 random images from 15 categories
26586 15 random First Geographs for 15 squares
25666 15 random images specified to a 10 figure grid reference
Location String (Postcode, Grid Reference or Lat/Long) Simply pass to search.php and the response from the server will include a brand new i number ready for use.

For example http://www.geograph.org.uk/search.php?q=SH3467 would return a
Location: http://www.geograph.org.uk/search.php?i=12345
header, just parse out that i number and pass it to the XML/CSV page.

UK(inc NI) Postcodes, e.g.
http://www.geograph.org.uk/search.php?q=TN32+3DZ

Lat/Long (Decimal Degrees only), example http://www.geograph.org.uk/search.php?q=52.332,-2.2345

Technically this can also accept place-names or free text search, however due to there being no guarantee that it will only match one place-name (or none and run a text search), if it's not sure it returns a page asking the user to confirm their meaning.

However it's possible to pass a numeric place-name id, please contact us if you would be interested in a copy of the dataset that we use.
Advanced It's also possible to build more complicated searches using the advanced search form. Either build a search using the form and make note of the resultant i number, or have a look at the source code to see the parameters possible.

Due to fact that the exact parameters are subject to change and have some inter-relations, it's probably easiest to contact us with the details of the type of searches you are trying to build.

Places to use an i number

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

Results Webpage http://www.geograph.org.uk/search.php?i=12345
Google Earth Webpage http://www.geograph.org.uk/kml.php?i=12345
Statistics Webpage http://www.geograph.org.uk/statistics/breakdown.php?i=12345
XML/HTML etc feed http://api.geograph.org.uk/syndicator.php?key=[apikey]&i=12345
CSV feed http://api.geograph.org.uk/export.csv.php?key=[apikey]&i=12345
MemoryMap feed http://www.geograph.org.uk/memorymap.php?key=[apikey]&i=12345 (Coming soon)
GPX Export http://api.geograph.org.uk/syndicator.php?key=[apikey]&format=GPX&i=12345

Other Ways to download information

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. Please consider joining the Geograph-API-Users Google Discussion Group, which is primarily used for announcements.



blog comments powered by Disqus
You are not logged in login | register
please support us