Geograph API Documentation
The Geograph Application Programming Interface (API) allows third-party developers to access and build applications using data sourced from Geograph in an efficient, structured manner.
The Geograph API is continuously evolving based on developer needs. If you are looking for alternative data access or have a specific use case, we have a variety of other APIs available that are not yet fully documented here. Please contact us with your feedback, feature requests, or custom requirements — we are always happy to help you find the right solution or build a custom endpoint rather than having you scrape the website.
Data License & Attribution Requirements
All data exports include the photographer's name and credit. To comply with our Creative Commons (CC) licensing, you must adhere to the following conditions:
- Display the photographer's credit alongside any use of the image.
- Explicitly state that the image is Creative Commons licensed.
- If you adapt the image, rather than just copying it “as is”, your new work must also be Creative Commons licensed (the ShareAlike clause).
Ideally, provide a link back to the original photo page using either the supplied URL or the format: https://www.geograph.org.uk/photo/[id].
Database Dumps (Bulk Data Download)
For heavy data requirements, we provide a raw mysqldump snapshot of the database. For download details and access, please visit data.geograph.org.uk/dumps.
We also offer a number of predefined image datasets curated specifically for machine learning and AI applications (with some packages also available directly via Kaggle). For more details, please see data.geograph.org.uk/datasets.html.
⚠ Authentication & API Keys
To access the live feeds documented below, you will need a unique API key. You can request a key here.
Once you have received your key, simply replace the [apikey] placeholder in the following examples to authenticate your requests.
Other APIs
Please see the Geograph Images APIs Article for information regarding other available APIs, including several options not fully detailed on this page.
Syndicator/RSS 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.org.uk/profile/120">David Stowell</user> <img src="https://www.geograph.org.uk/photos/00/34/003456_e10e23bc.jpg" crossorigin 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.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>
|
| 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.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>
Note:the distance should be 10km or below.
|
| https://www.geograph.org.uk/photo/[photo-id].rdf | |
| https://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
|
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
| -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.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: 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.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 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.org.uk/search.php?q=SH3467 would return a Location: https://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. https://www.geograph.org.uk/search.php?q=TN32+3DZ Lat/Long (Decimal Degrees only), example https://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 | https://www.geograph.org.uk/search.php?i=12345 |
| Google Earth Webpage | https://www.geograph.org.uk/kml.php?i=12345 |
| Statistics Webpage | https://www.geograph.org.uk/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
- We can also create coverage CSVs on demand, (listing squares currently with images)
- We can provide Leaflet Map Tiles, showing either explicit photo locations, or gridded coverage layers
- 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
