Skip to content
API for retrieving item information, availability and location of common goods.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
img
LICENSE
README.md updated image, linked presentation Mar 8, 2019
commons-api.schema.json
package.json trying to fix missing velogistics json file in npm package Feb 4, 2019
velogistics-api.schema.json fixed typo (wheels instead of nr_of_wheels) Feb 20, 2019

README.md

Commons API

API for retrieving item information, availability and location of common good item(s), defined as a JSON schema.

commons-api-overview

This project aims to create a standard format for exchanging information between software used by grassroots organisations to lend common goods. Based on this API, an open source "Commons Hub" software package is in development. The "Commons Hub" allows users to browse the items that all participating initiatives are offering.

By design, the API will not be collecting/sharing any user data, individual projects will remain in total control.

The Commons Api uses the GeoJson format for locations. Each location is a GeoJson feature with a GeoJson point containing its coordinates. Locations are stored in GeoJson FeatureCollection.

Example

{
  "project": {
    "name": "V",
    "url": "http://localhost/",
    "description": "Just another WordPress site",
    "language": "en_US"
  },
  "items": [
    {
      "uid": "1",
      "name": "Cargo Bike Blue",
      "url": "http://localhost/item/cargo-bike-blue/",
      "owner_uid": "1",
      "availability": [
        {
          "status": "available",
          "start": "2019-01-24T08:00:00",
          "end": "2019-01-24T08:00:00",
          "location_uid": "4"
        },
        {
          "status": "booked",
          "start": "2019-01-25T08:00:00",
          "end": "2019-01-25T08:00:00",
          "location_uid": "4"
        }
      ],
      "description": "My favorite bike."
    }
  ],
  "owners": {
    "1": { "name": "admin", "url": "http://localhost/author/admin/" }
  },
  "locations": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [123456, 123456]
        },
        "properties": {
          "uid": "4",
          "name": "Berlin biscuits",
          "url": "http://localhost/location/berlin-biscuits/"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [123456, 123456]
        },
        "properties": {
          "uid": "3",
          "name": "Budapest fairest",
          "url": "http://localhost/location/budapest-fairest/"
        }
      }
    ]
  }
}

Extending the API with item metadata

The Commons Api scheme is thought of as a basis from which to start. Providers should create their own schemas that add specific metadata to the base scheme. This can be done by using "allOf" with "additionalProperties" set to false. See the JSON schema reference on combining schemes for further details.

This repository contains the Velogistics Api for cargobikes as an example for this.

Contributing

We are looking for contributers, both developers and sharing initiatives.

Implementation

See our presenation at FFL2019: Datei:Florian Egermann Presentation CommonsBooking FFL2019.pdf – Forum Freie Lastenräder

As a first step, we are working to implement the API into 2 projects that are already widely used to share cargo bikes:

  • Booking software: Commons Booking (Wordpress Plugin, used by over 60 sharing initiatives)
  • Hub: velogistics.net (Cargobike-sharing portal with more than 250 available bikes)

Commons Booking provides initiatives with a tool to manage and lend common goods, the successor of velogistics will serve as the hub connecting the individual installations.

Draft

The API is defined in a JSON schema in this repository. We have used schema descriptions to self-document the format. You can use the JSON schema validator to try out the schema. Just paste the file content into the left field and start to compose your first Commons API data.

[TODO]: Add Example of a json return for a bike from the commons cargobike project http://kasimir-lastenrad.de.

You can’t perform that action at this time.