OpenBenches

https://OpenBenches.org/ - an open data repository for memorial benches.

Contributing

All contributions are welcome. Before making a pull request, please:

1. Raise a new issue describing the problem and how you intend to fix it.
2. Submit a Pull Request referencing the Issue.

Open Data API

You can get all the data, or partial data, from the API. Data is returned in geoJSON format.

Benches

• All Bench Data
  • https://openbenches.org/api/v1.0/data.json/
  • That last / is required.
• Specific Bench
  • https://openbenches.org/api/v1.0/data.json/?bench=123
• Geographic Area (Haversine)
  • https://openbenches.org/api/v1.0/data.json/?latitude=51.234&longitude=-1.234&radius=20&results=5
  • latitude and longitude in WGS 84.
  • radius in Kilometres.
  • results maximum number of benches returned. By defaults, 20 results are returned.
• Tags
  • https://openbenches.org/api/v1.0/data.json/?tagText=cat
  • Returns all the benches with a specific tag.
• Inscriptions
  • By default, the inscriptions are truncated to 128 characters.
  • To get the full inscriptions, append &truncated=false
  • https://openbenches.org/api/v1.0/data.json/?truncated=false
• Formats
  • By default, the JSON starts with var benches =
  • To get pure JSON, append &format=raw
  • https://openbenches.org/api/v1.0/data.json/?bench=123&format=raw
• Media
  • By default, the API doesn't return media.
  • To get media, append &media=true

Tags

• All available folksonomy tags
  • https://openbenches.org/api/v1.0/data.json/
  • That last / is required.
  • Returned in a format suitable for Select2.

Users

• All User Data
  • https://openbenches.org/api/v1.0/users.json/
  • That last / is required.
• Specific User
  • https://openbenches.org/api/v1.0/users.json/?userID=1234
• Formats
  • By default, the JSON starts with var users =
  • To get pure JSON, append &format=raw
  • https://openbenches.org/api/v1.0/users.json/?userID=1234&format=raw

Alexa Skill

There is an Alexa Skill which allows you to interact with the site via your voice. This functionality is provided by an API.

• How many benches have been uploaded
  • https://openbenches.org/api/v1.0/alexa.json/?count
• The latest bench
  • https://openbenches.org/api/v1.0/alexa.json/?latest
• Details of a random bench
  • https://openbenches.org/api/v1.0/alexa.json/?random
• Formats
  • By default, the JSON starts with var alexa =
  • To get pure JSON, append &format=raw
  • https://openbenches.org/api/v1.0/users.json/?format=raw&count

Running Locally

This is a simple PHP and MySQL website. No need for node, complicated deploys, or spinning up containerised virtual machines in the cloud.

Requirements

• PHP 7 or greater.
• MySQL 5.5 or greater with innodb.
• ImageMagick 6.9.4-10 or greater.

External APIs

You will need to sign up to some external API providers:

• Map display requires a Stadia Maps account
• Reverse Geocoding requires an OpenCage API key
• Flickr Import requires a Flickr API key
• Tweeting requires a Twitter Developer API key
• Text detection requires a Google Cloud Vision API key
• Image resizing and caching requires a CloudImage.io account. (But note: this requires your development webserver to be accessible from the internet)
• Optional Login requires a free Auth0.com account.
• Optional Satellite Map display requires a free Mapbox account

Add them to config.php.example - rename that to config.php

Database Structure

In the /database/ folder you'll find a sample database. All text fields are utf8mb4_unicode_ci because we live in the future now.

Hopefully, the tables are self explanatory:

Benches

• benchID
• latitude
• longitude
• address text representation generated by reverse geocoding. For example "10 Downing Street, London SW1A 2AA, United Kingdom"
• inscription the text written on the bench
• description placeholder. Might be used for comments about the bench.
• present if a bench has been physically removed, this can be set to false.
• published set to FALSE if the bench has been deleted
• added datetime of when the bench was uploaded to the site
• userID foreign key

Users

Originally we were going to force people to sign in with Twitter / Facebook / GitHub. But that discourages use - so users are now pseudo-anonymous. Hence this weird structure!

• userID
• provider could be Twitter, GitHub, Facebook etc.
• providerID user ID number on the provider's service. Anonymous users stores their IP address.
• name their display name. Anonymous users stores the time they added a bench.

Media

We store the original image - smaller images are rendered dynamically.

Media storage can be complicated. Storing thousands of images in a single directory can cause problems on some systems. To get around this, we calculate the SHA1 hash of each image. The image is stored in a subdirectory based on the hash. For example, if the hash is 1A2B3C, the file will be stored in /photos/1/A/1A2B3C.jpg

• mediaID
• benchID
• userID
• sha1 A hash of the file.
• importURL If the image was imported from an external source - like Flickr.
• licence The default is CC BY-SA 4.0, imported images may be different.
• media_type We allow different types of photo - in the future, we might have other types of media.
• width The image's width in pixels.
• height The image's width in pixels.
• datetime The date and time the image was created - based on EXIF metadata.
• make The make of camera which took the photo - based on EXIF metadata.
• model The model of camera which took the photo - based on EXIF metadata.

Media Types

At the moment, we only accept photos - of the inscription, the bench, the view from the bench, a panorama, and a VR photosphere.

• shortName Internal ID.
• longName Displayed to the user.
• displayOrder When rendering a form in HTML, this determines the order they are presented in.

Licences

• shortName Internal ID.
• longName Displayed to the user.
• url For more information.

Tagging

Benches can be given multiple "tags". For example "cat" if the bench commemorates a feline, or "beach" if the bench is at the seaside.

Tagging uses the Toxi structure.

• tags contains:

  • tagID a unique ID
  • tagText the displayed text

• tag_map contains:

  • mapID a unique ID
  • tagID the ID of a tag
  • benchID the ID of a bench

Tags are hard-coded in the database and can't be added or edited by regular users.

Open Source Licenses

Everything we do builds on someone else's hard work.

• OpenBenches data are made available under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).
• The code powering the website is MIT.
• All photos uploaded by users are CC BY-SA 4.0.
• Benches from Bath are OGL and Powered by Bath: Hacked.
• Logo template by Creative Mania CC BY.
• Twitter integration by CodeBird GPL v3.
• Maps by Leaflet BSD 2-clause "Simplified" License.
• Cluster library by Leaflet MIT.
• Map tiles by MapBox.
• GPS logo by Chinnaking CC BY.
• Panoramic Visualiser by Pannellum MIT.
• JavaScript EXIF reader & image preview by JavaScript Load Image (MIT).
• Login services provided by Auth0.com's PHP library MIT.
• CSS based on PicniCSS MIT (chosen mostly because we like picnic benches!)
• Tagging library by Select2 MIT
• Animated OCR icon by Loading.io CC BY.

And thanks to the many contributors who have improved this codebase.