Upcoming Change to Geograph API Response for lat/long searches

[barryhunter]

(if not running latitude/longitude centered searches can stop reading now!)

We are currently implementing a new backend for the API servers, which is quicker and more scalable. The new backend is about 50ms faster on average, which may seem small, but over thousands of API requests, it quickly adds up. 

... this will mean a slight change to the API response format, although hopefully it shouldn't affect most uses. We intend to change over automatically 1st Feb 2021, but can test it now. At the moment it only affects lat/long centered searches (which are the most common type of request to the API) - other queries may follow later. 

Current API example:
https://api.geograph.org.uk/api/latlong/1km/60.81990051,-0.77726584/key?output=json&limit=12
or

https://api.geograph.org.uk/syndicator.php?format=JSON&location=58.93180084,-3.35141165&distance=1

New format:
https://api.geograph.org.uk/api/latlong/1km/60.81990051,-0.77726584/key?output=json&limit=12&new=1

or  

https://api.geograph.org.uk/syndicator.php?format=JSON&location=58.93180084,-3.35141165&distance=1&new=1

(add the new=1 param to signal using the new system)

Please test the new API, see if it works for you. If you wish, you can immediately switch to the new format by adding &new=1 in your 'production' site. It will be safe to leave that parameter there long term even after the current backend is withdrawn. Otherwise can just wait until it automatically changes over. 

Notable Changes: 

1. The top level description is more generic. just says 'Images Nearby' without coordinate, although it still provides the total number of results
2. No longer provides the  syndicationURL and  nextURL (as it no longer creates a canned search) - but it doesn't appear that these are in regular use
3. And some fields are now missing from the 'items' (ie photos) array, 
   1. item.description is missing, (the long textual description)
   2. item.dateUpdated is missing (timestamp of last update)
   3. item.tags list will be more shuffled, it used to be roughly in order of creation. but more arbitrary now.  Although all tags are still present!
   4. seq_no field is missing (sequence of the image within its square) 
   5. ftf field is also missing (shows the firsts in square) 
      

(not all fields are present in each format anyway, so might not see those fields anyway) 

Otherwise should be equivalent, the actual images results should be the same, although sometimes in slightly different order (eg when distance is the same)! Except in one edge case, if the lat/long coordinates didnt match a known square (i.e. somewhere in the sea, or outside British Isles!) the old version would 'fallback' to provide a keyword result using the numbers, sometimes giving nonsense results. It's an edge case that didn't crop up very often. very few users should ever have seen that ... the new one will instead say (correctly) no results!

The changes apply regardless of the output 'format' you use (e.g. if you use RSS rather than JSON). 

Particularly interested, if you actually have a use for the image description(comment), we could consider adding support for that if needed (although wouldnt be enabled by default)

As noted, we intend to move everyone over to the new system, but giving some heads up to allow the new version to be tested in advance, and also to let us know if you actually used the fields that are now missing!

PS. If interested in technical details

https://github.com/geograph-project/geograph-project/commit/12ffda8b7225b7c2c769b34d01712cbc17bb61cd