Please Note: This page is not complete. We have many other APIs available, that we havn't got round to documenting.

For a general overview, please see: Geograph Images APIs Article, suggest new visitors start there.

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.

Geograph API Documentation (last updated 1st May 2012)

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.



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 https://www.geograph.ie/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.

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

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
https://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
https://api.geograph.org.uk/syndicator.php?key=[apikey]&i=12345
u=[user_id] Limit results to particular user
https://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)
https://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)
https://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)
https://api.geograph.org.uk/syndicator.php?key=[apikey]&text=bridge

Options

callback=[function] wraps the output in a function call. Only works with format=JSON, to allow use in client-side Javascript web-apps
https://api.geograph.org.uk/syndicator.php?key=[apikey]&format=JSON&callback=function
expand=1 If present includes the thumbnail of the image in the description as html (not applicable to KML format).
https://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="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

https://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="https://www.geograph.ie/profile/120">David Stowell</user> 
  <img src="https://www.geograph.ie/photos/00/34/003456_e10e23bc.jpg" crossorigin="anonymous" width="640" height="480" style="image-orientation:none"/> 
</geograph>
(the crossorigin and style, are needed if you going to render the image in a webpage, as it forces the browser to ignore the EXIF rotation/oritentiation flag, which is incorrectly set on a small minority of images. If going to take a copy and serve the file from your own domain, it not needed)
https://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="https://www.geograph.ie/photo/64854">
    <title>Afon Cynfal</title> 
    <user profile="https://www.geograph.ie/profile/3">Barry Hunter</user> 
    <img src="https://www.geograph.ie/photos/06/48/064854_d68e7342_120x120.jpg" width="90" height="120" /> 
    <location grid="1" eastings="270500" northings="341100" /> 
  </image>
</geograph>
https://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: https://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="https://www.geograph.ie/photo/1575413"> 
    <title>St Nicholas Hall</title>
    <user profile="https://www.geograph.ie/profile/17441">David Lally</user> 
    <img src="https://www.geograph.ie/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.
https://www.geograph.ie/photo/[photo-id].rdf
https://www.geograph.ie/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:

https://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
https://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.
https://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
https://api.geograph.org.uk/export.csv.php?key=[apikey]&last=7+DAY
https://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)
https://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)
https://api.geograph.org.uk/export.csv.php?key=[apikey]&ri=1 - Great Britain
https://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')
https://api.geograph.org.uk/export.csv.php?key=[apikey]&i=12345
encoding=utf8 Get the CSV in UTF-8 encoding - otherwise will get latin1/ISO-8859-1 (with HTML Entities for extended chars).
Most other APIs output UTF-8 anyway, but for legacy reasons the CSV export would output latin1 (which is the encoding in our internal database) NOTE: can be used with all of the above parameters
https://api.geograph.org.uk/export.csv.php?key=[apikey]&encoding=utf8

* 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
https://www.geograph.ie/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: The "en" and/or "ppos" options can't be used at same time as "ll" and/or "tags"

&taken=1 taken date of the image 2008-07-22
&en=1 add this parameter to add the Eastings, Northings and Precision
https://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:
https://www.geograph.ie/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 Camera Position
https://api.geograph.org.uk/export.csv.php?key=[apikey]&ppos=1
  Easting Absolute position for the camera 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 Camera 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.
&points=1 points awared (1/2/3/4/personal/tpoint) space separated
&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 https://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 https://www.geograph.ie/search.php?q=SH3467 would return a
Location: https://www.geograph.ie/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.
https://www.geograph.ie/search.php?q=TN32+3DZ

Lat/Long (Decimal Degrees only), example https://www.geograph.ie/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 https://www.geograph.ie/search.php?i=12345
Google Earth Webpage https://www.geograph.ie/kml.php?i=12345
Statistics Webpage https://www.geograph.ie/statistics/breakdown.php?i=12345
XML/HTML etc feed https://api.geograph.org.uk/syndicator.php?key=[apikey]&i=12345
CSV feed https://api.geograph.org.uk/export.csv.php?key=[apikey]&i=12345
GPX Export https://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.



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