Geograph Image APIs

We have a number of APIs for accessing over 6.2 million Geograph Images, each have evolved at a different time in the project's history, with somewhat overlapping features. There is the 'offical' documentation page at https://www.geograph.org.uk/help/api - but its a bit of a confusing mess now. It doesn't provide a high-level overview, so that is what this page attempts to do.

Note this page only concentrates on APIs for retrieving actual images, we have many more APIs providing meta-data, and aggregate statistics and the like. See: Link


Most APIs need a API key, when using these APIs don't forget to honour the Creative Commons licence. Currently ALL images use Attribution-ShareAlike 2.0 Generic (CC BY-SA 2.0)

For what the other Geograph projects offer, see http://www.geograph.org/downloads.php

Live APIs

Syndicator API

• Good For: RSS-style access, and simple queries
• Pros: Can be used with systems that expect standard RSS feeds. Also can output KML, JSON etc. Easiest API to use.
• Cons: Not great performance, arcane interface. Only good for simple implementations
• Documentation: Link
• Endpoint: http://api.geograph.org.uk/syndicator.php
• Live Demo: Link

High Resolution Wallpaper Feed

• Good For: Screensavers, demos, source of inspiring images
• Pros: very simple API, provides direct access to high-resolution stamped images (so easy to reuse). Has a range of filtering options.
• Cons: only offers pre-curated selections
• Documentation: Link
• Endpoint: https://api.geograph.org.uk/api-wallpaper.php?format=JSON
• Live Demo: Link (the documentation is in the form of a interactive Javascript demo)

Full-Text Search API

• Good For: General and realtime access of images (Is the recommended API to use, but is the most complicated!)
• Pros: Very fast performance and flexible query options. Can do 'grouping' or aggregation queries too.
• Cons: Does very little of the presentation of data, eg the client has to form image urls itself. Can't obtain the image description.
• Documentation: See 'Facets API' on: Link
• Endpoint: http://api.geograph.org.uk/api-facetql.php
• Live Demo: Link - a javascript client side application, almost exclusively powered by this API!
• There is a 'polyfill' API just to get description Link
• Interested in displaying photos in a Leaflet based Web Map? See this plugin: Link uses this API, but does the 'heavy lifting' of displaying photos.

oEmbed API

• Good For: Getting information for a known image URL
• Pros: very simple interface. multiple formats
• Cons: no query capalities, one specific purpose.
• Documentation: http://oembed.com/ (Geograph is listed in 'Implementations)
• Endpoint: http://api.geograph.org.uk/api/oembed

Database Dumps

• Good For: Downloading complete database!
• Pros: complete data in bulk.
• Cons: Rather raw, needs piecing together. Trickly to keep local copy updated.
• See Link

Others

We also have these other APIs, but limited interest now.

Database Extractor

• Good For: One-off extracts of a subset of data.
• Pros: Can choose what columns want, and also filter to only interesting rows
• Cons: based on a outdated dump. Not for 'automated' use.
• See Link

Rest API

• Good For: Specific access to limited data
• Pros: can get information to specific images, or a gridsquare
• Cons: very limited scope
• Documentation: Link
• Endpoint: http://api.geograph.org.uk/api/

CSV API

• Good For: Simple interface to small amounts of data
• Pros: compact data format, access to most metadata.
• Cons: Depreciated! Bad Performance. (was ok when Geograph only had 'thousends' of images)
• Documentation: Link
• Endpoint: http://api.geograph.org.uk/export.csv.php

Torrents Download

We used to host a torrent tracker with rebuild bulk dumps, but is now offline Link

Instead a sample of images is uploaded to Archive.org: Link
... we haven't got round to uploading everything, but might if there is interest.

-------

If unsure, please ask: https://www.geograph.org.uk/contact.php

---