CitySDK Linked Open Data Distribution API

GET Interface

Read access to nodes

GET /nodes Returns a list of nodes, as specified through url parameters (see below). You will want to limit the selection on geography, tag or with layer specifications. Without layer spec, only the node information itself is returned.
GET /routes Returns a list of defined 'routes', see above with 'nodes'; you'll want to limit the selection.
GET /regions Returns a list of defined administrative regions, see above with 'nodes'; you'll want to limit the selection, usually.
GET /ptstops Returns a list of defined public transport stops.
GET /ptlines Returns a list of public transport lines.

URL parameters

There are several ways to specify and narrow down the extend of your request. You can specify the geographic area of interest (other than searching 'within' an area, as described below), limit your request to data and nodes on specific layers, and do searches on name or on specific data in specified layers. These options are passed through url parameters. Parameters can be combined in a single request, where this makes sense.

?per_page=<num> Limits the number of returned nodes to <num>. Defaults to 10. The maximum value is capped in the backend, currently to 1000 nodes. Multiple requests may be necessary to get all the data for a request.
?page=<num> Requests page <num>.
?name=<string> Most nodes have a name. This parameter allows you to do a sub-string search on that name. The search is case-insensitive and returns nodes whith the specified <string> anywhere in the name.
?layer=<name> Limits the request to nodes that have data on any or all of the specified layers. <name> is a single layer or a comma-separated (AND) or pipe-separated (OR) list of layer names. Wildcards can be used after layer name separators. Examples are ?layer=admr,cbs; ?layer=divv.*|gtfs. Logic cannot be mixed, it is either all ANDs or all ORs.
?<layer>::<key>[=<val>] Returns nodes with specified key-value pairs on specified layers. When =<val> is ommitted, returns nodes with any value present for that key. For example: ?osm::tourism=museum returns all nodes with museums on the osm layer, where ?osm::tourism returns any osm node with the tag 'tourism'. You can specify multiple key-value pair filters in a single GET request. By default, only nodes are returned which satisfy all specified key-value pair filters (AND), but you can change this behaviour by setting URL parameter ?data_op=or. Then, all nodes are returned which satisfy any of the specified filters. For example, ?osm::tourism=museum|zoo&osm::amenity=theatre&data_op=or will return all OSM nodes that are either a museum, a zoo or a theatre.
This returns nodes within the specified radius (in meters) around lat/lon. Without the radius parameter the request returns the <per_page> geographically closest matches to lat/lon.
?bbox=[<t>,<l>,<b>,<r>] Match nodes within the given bounding box. Order of the coordinates is top, left, bottom, right.
?geom Returns the geometry values of the nodes. No parameter value. When not present the geometry is not returned; this can save considerable bandwidth when node geometries are not needed.
?count Returns the total of matched nodes in the results. Default is off, as counting can have a considerable impact on performance.

The following URL parameters are used to filter routes by the nodes they consist of:

?starts_in=<cdk_id> Returns routes starting in a specific node.
?ends_in=<cdk_id> Returns routes ending in a specific node.
Returns routes containing a specific set of nodes, in the correct order. The contains parameter takes at least one cdk_id, but you can also specify more nodes in a comma-separated list.

Access to elements within a geographic boundary

Apart from limiting your selection to bounding box or circle radius parameters in the url (see below), more ususally you'll want to limit the selection to a particular (administrative) region. The node your are specifying as a boundary can be any node, really, but will only make sense in the case of a node with definite area.

GET /<cdk_id>/nodes All nodes geographically intersecting with node <cdk_id>.
GET /<cdk_id>/routes All routes.
GET /<cdk_id>/regions All regions.
GET /<cdk_id>/ptstops All public transport stops.
GET /<cdk_id>/ptlines All public transport lines.

Interface to individual nodes

GET /<cdk_id> Returns data of the node specified. Useful in combination with layer url parameter to return the node together with data on specified layers. Otherwise, only the node's cdk_id, layer, name and, optionally, geometry is returned.
GET /<cdk_id>/<layer> Shortcut to access node data on a specific layer. Differs from the layer url parameter in that this only returns the node data, not the node itself.
GET /<cdk_id>/<layer>
Access specific piece of data on a specific layer, see examples.


GET /layers Returns a list of the layers currently defined; a general Overview of data available in the endpoint. Layers can be searched for by name and by category: GET /layers?name=divv.* or GET /layers?category=mobility
GET /layer/<name> Returns information on the specified layer.


Information on nodes can be static, or dynamic. Also, some information is not stored as such, but can be derived from the data that is. To provide an interface to these kinds of data, some types of nodes can be queried through the select command. The general form of this command is /<cdk_id>/select/<command> Currently the following commands are defined:

On nodes:

GET /<cdk_id>/select/regions will list the administrative region hierarchy starting at this node.
GET /<cdk_id>/select/routes will list routes containing this node.
GET /<cdk_id>/select/routes_start will list routes starting in this node.
GET /<cdk_id>/select/routes_end will list routes ending in this node.

On routes:

GET /<cdk_id>/select/nodes will list the nodes that make up a route.
GET /<cdk_id>/select/routes will list the routes which nodes intersect with the nodes of route with /<cdk_id>.
GET /<cdk_id>/select/start_end will list the start and end node of a route.

On ptstops:

GET /<cdk_id>/select/ptlines will list the public transport lines that frequent a stop
GET /<cdk_id>/select/schedule will list the schedule for the coming week for all lines that stop at this stop.
GET /<cdk_id>/select/now will, for eacht line at this stop, give you the (real-time) departure times for the coming hour.

On ptlines:

GET /<cdk_id>/select/ptstops will list the public transport stops that make up a pt line.
GET /<cdk_id>/select/schedule will list the schedule for today; adding ?day=<n> will list schedule for the <n> days from now.