...
 
Commits (2)
......@@ -3,8 +3,8 @@
[![pipeline status](https://gitlab.com/evanp/places-pub/badges/master/pipeline.svg)](https://gitlab.com/evanp/places-pub/commits/master)
This is the source code for the [places.pub](https://places.pub/) service. It
provides a vocabulary for [Activity Streams 2.0](https://www.w3.org/TR/activitystreams-core/) [Place](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-place) objects,
using the [OpenStreetMap](https://openstreetmap.org/) vocabulary.
provides a home for [Activity Streams 2.0](https://www.w3.org/TR/activitystreams-core/) [Place](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-place) objects,
using the [OpenStreetMap](https://openstreetmap.org/) database.
## LICENSE
......@@ -24,92 +24,4 @@ limitations under the License.
## How to use it
There are four important kinds of URLs for places.pub, as defined by the following [URI templates](https://tools.ietf.org/html/rfc6570).
### <https://places.pub/osm/node/{id}>
Represents a single Place defined by the OpenStreetMap node ID number `id`.
The server will do [content negotation](https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html) to figure out what kind of content to return. This will usually be either HTML or Activity Streams 2.0 JSON.
### <https://places.pub/osm/way/{id}>
Represents a single Place defined by the OpenStreetMap way ID number `id`.
The server will do [content negotation](https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html) to figure out what kind of content to return. This will usually be either HTML or Activity Streams 2.0 JSON.
### <https://places.pub/osm/search?{?q,lang,lat,lon,d}>
Finds OpenStreetMap places that match the search terms, possibly within a bounding box.
* `q`: Free text search term, like `Montreal` or `Slanted Door`. Optional.
* `lang`: Language code for the free text search term. Optional, defaults to
Esperanto, `eo`. Kial ne?
* `lat`: Latitude of center of bounding box, in decimal form. Optional.
Generates an error if provided without `lon`.
* `lon`: Longitude of center of bounding box, in decimal form. Optional.
Generates an error if provided without `lon`.
* `d`: Half of the length of one edge of the bounding box, in meters.
Generates an error if provided without `lat` and `lon`. Optional.
Defaults to 50
* `page`: page of results to return. The page length is 10.
Some examples of good queries:
* <https://places.pub/osm/search?q=Montréal?lang=fr>
* <https://places.pub/osm/search?q=Montreal?lang=en>
* <https://places.pub/osm/search?lat=52.36304325&lon=4.88285962668329>
* <https://places.pub/osm/search?q=de+Balie&lat=52.36304325&lon=4.88285962668329>
* <https://places.pub/osm/search?q=de+Balie&lat=52.36304325&lon=4.88285962668329&d=100>
* <https://places.pub/osm/search?q=McDonalds&offset=240&limit=10>
* <https://places.pub/osm/search?q=McDonalds&before=N433592579>
* <https://places.pub/osm/search?q=McDonalds&after=N433592579&limit=10>
The server will do [content negotation](https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html) to figure out what kind of content to return. This will usually be either HTML or Activity Streams 2.0 JSON.
If it is AS2, it will be a [collection](https://www.w3.org/TR/activitystreams-core/#collections)
with a `first` property being the first page of results, unless the `page`
parameter is provided, in which case it will be a [CollectionPage](https://www.w3.org/TR/activitystreams-core/#dfn-collectionpage).
The `first`, `last`, `next` and `prev` properties are useful for paging.
### <https://places.pub/version>
Returns the version of the places.pub API currently in use. This follows [semantic versioning](http://semver.org/), such that:
Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as
extensions to the MAJOR.MINOR.PATCH format.
(...as stated on the Semver site.) Note that this will probably but not
necessarily track to the places.pub software version.
The server will do [content negotation](https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html) to figure out what kind of content to return. This will usually be either HTML or JSON.
If it is JSON, it will be single string, containing the version.
In the future, if there are incompatible versions of this API, we'll probably
do something to make sure old software doesn't break, like move the new
version of the API to `/osm/v2/` or something.
## Ways and nodes
Because its main use is for drawing maps, OpenStreetMap's data model
differentiates between points on the map (*nodes*) and multi-node figures
(*ways*). However, this isn't that important for most ActivityPub applications,
so we map both of them to the ActivityStreams 2.0 Place type.
However, they have a different namespace, and it's possible that there are nodes
with the same ID as a way. So, you have to ask for them differently.
This only matters if you're coming to places.pub with an OpenStreetMap ID and
trying to get an AS2 representation. If that's the case, you have to know the
type, too.
For search results, the ID will include the right type, so you shouldn't have to
worry about it. Just use the full ID value for a Place to get its data from
places.pub.
The [API](https://places.pub/api) page documents the API for the service.
......@@ -72,6 +72,10 @@ app.get('/', (req, res) => {
res.render('index', {title: 'Home'})
})
app.get('/api', (req, res) => {
res.render('api', {title: 'API'})
})
app.get('/version', (req, res) => {
res.json(version)
})
......
......@@ -2733,5 +2733,5 @@
}
}
},
"version": "0.8.1"
"version": "0.9.0"
}
......@@ -31,5 +31,5 @@
"pug": "^2.0.0-rc.4",
"yargs": "^10.0.3"
},
"version": "0.8.1"
"version": "0.9.0"
}
......@@ -3,5 +3,4 @@ body {
}
.starter-template {
padding: 40px 15px;
text-align: center;
}
......@@ -67,6 +67,7 @@ vows.describe('app loads and listens on correct port')
assert.isObject(server)
},
'and we fetch the home page': checkUrl('/'),
'and we fetch the api page': checkUrl('/api'),
'and we fetch the Bootstrap CSS': checkUrl('/bootstrap/css/bootstrap.min.css'),
'and we fetch the JQuery JS': checkUrl('/jquery/jquery.min.js'),
'and we fetch the Bootstrap JS': checkUrl('/bootstrap/js/bootstrap.min.js'),
......
extends layout.pug
block content
h1 places.pub API
p
| There are four important kinds of URLs for places.pub, as defined by the
| following&nbsp;
a(href="https://tools.ietf.org/html/rfc6570") URI templates
| .
h2 https://places.pub/osm/node/{id}
p Represents a single Place defined by the OpenStreetMap node ID number `id`.
p
| The server will do content negotiation to figure out what kind of content to
| return. This will usually be Activity Streams 2.0 JSON.
h2 https://places.pub/osm/way/{id}
p Represents a single Place defined by the OpenStreetMap way ID number `id`.
p
| The server will do content negotiation to figure out what kind of content to
| return. This will usually be Activity Streams 2.0 JSON.
h2 https://places.pub/osm/search?{?q,lang,lat,lon,d}
p
| Finds OpenStreetMap places that match the search terms, possibly within a
| bounding box.
ul
li `q`: Free text search term, like `Montreal` or `Slanted Door`. Optional.
li `lat`: Latitude of center of bounding box, in decimal form. Optional.
| Generates an error if provided without `lon`.
li `lon`: Longitude of center of bounding box, in decimal form. Optional.
| Generates an error if provided without `lon`.
li `d`: Half of the length of one edge of the bounding box, in meters.
| Generates an error if provided without `lat` and `lon`. Optional.
| Defaults to 50
li `page`: page of results to return. The page length is 10.
p
| The server will do content negotation to figure out what kind of content to
| return. This will usually be either HTML or Activity Streams 2.0 JSON.
p
| If it is AS2, it will be an AS2 Collection
| with a `first` property being the first page of results, unless the `page`
| parameter is provided, in which case it will be a CollectionPage.
| The `first`, `last`, `next` and `prev` properties are useful for paging.
h2 https://places.pub/version
p
| Returns the version of the places.pub API currently in use. This follows
p
| (...as stated on the Semver site.) Note that this will probably but not
| necessarily track to the places.pub software version.
p
| The server will do content negotation to figure out what kind of content to
| return. This will usually be either HTML or JSON.
p If it is JSON, it will be single string, containing the version.
p
| In the future, if there are incompatible versions of this API, we'll probably
| do something to make sure old software doesn't break, like move the new
| version of the API to `/osm/v2/` or something.
h2 Ways and nodes
p
| Because its main use is for drawing maps, OpenStreetMap's data model
| differentiates between points on the map (*nodes*) and multi-node figures
| (*ways*). However, this isn't that important for most ActivityPub applications,
| so we map both of them to the ActivityStreams 2.0 Place type.
p
| However, they have a different namespace, and it's possible that there are nodes
| with the same ID as a way. So, you have to ask for them differently.
p
| This only matters if you're coming to places.pub with an OpenStreetMap ID and
| trying to get an AS2 representation. If that's the case, you have to know the
| type, too.
p
| For search results, the ID will include the right type, so you shouldn't have to
| worry about it. Just use the full ID value for a Place to get its data from
| places.pub.
......@@ -16,15 +16,13 @@ html(lang='en')
span.icon-bar
span.icon-bar
span.icon-bar
a.navbar-brand(href='#') places.pub
a.navbar-brand(href='/') places.pub
#navbar.collapse.navbar-collapse
ul.nav.navbar-nav
li.active
a(href='#') Home
a(href='/') Home
li
a(href='#about') About
li
a(href='#contact') Contact
a(href='/api') API
///.nav-collapse
.container
.starter-template
......