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)
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.
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/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...
-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:
|
||||||||
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:
|
||||||||
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:
|
||||||||
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:
|
||||||||
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.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:
|
||
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)
Returns an XML infoset of surrounding images, currently returns:
Example: https://api.geograph.org.uk/syndicator.php?format=JSON&q=[lat],[long]&distance=[distance]&key=[apikey] <?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
|
CSV Export
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
-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.
|
|||||||
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:
|
|||||||
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
|
||||||||||
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
- 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.
blog comments powered by Disqus