OpenBenches.org - an open data repository for memorial benches
PHP HTML CSS
Latest commit 19839c9 Oct 17, 2017 @edent edent Fix footer
Fixes #130

README.md

OpenBenches

A bench in a park, birds fly up above. In the background is a tree. https://OpenBenches.org/ - an open data repository for memorial benches.

BETA

OMG! This code is still a bit horrible. Looking at it will make you a bit sad. This is a slightly grubby beta - thrown together to test whether things work, but now we are sharing the blame with all the folks who have contributed so far.

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.

  • All Data
    • https://openbenches.org/data.json/
  • Specific Bench
    • https://openbenches.org/data.json/?bench=123
    • That last / is required.
  • Geographic Area (Haversine)
    • https://openbenches.org/data.json/?latitude=51.234&longitude=-1.234&radius=20
    • latitude and longitude in WGS 84.
    • radius in Kilometres.
    • A maximum of 20 results are returned.
    • That last / is required.
  • Formats
    • By default, the JSON starts with var benches =
    • To get pure JSON, append format=raw
    • https://openbenches.org/data.json/?bench=123&format=raw
  • Images
    • The API doesn't return images. Yet.

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:

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
  • description placeholder. Might be used for comments about the bench.
  • present placeholder. If a bench has been physically removed, this can be set to false.
  • published
  • added datetime
  • 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, etc.
  • providerID user's name 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.

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.

Open Source Licenses

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