API Endpoints

Note

For POST requests the fields are given analogous to GET requests. When you just have a smaller set of spatial parameters, a GET request fits perfectly. POST mostly makes sense when you start to use GeoJSON as input geometries.

The usage of the types, keys, values parameters is not recommended as they are deprecated. Please use the filter parameter for your requests.

Aggregation Endpoints

POST /elements/(aggregation)

Get aggregation of OSM elements.

  • aggregation type: one of area, count, length, perimeter

Query Parameters
  • <boundary> – One of these boundary parameters: bboxes, bcircles, bpolys. See boundaries

  • filter – combines several attributive filters: OSM type, geometry (simple feature) type, as well as the OSM tag; See filter

  • format – ‘json’ or ‘csv’; default: ‘json’

  • keys – OSM key(s) given as a list and combined with the ‘AND’ operator; default: empty

  • showMetadata – add additional metadata information to the response: ‘true’, ‘false’, ‘yes’, ‘no’; default: ‘false’

  • time – ISO-8601 conform timestring(s); default: latest timestamp in the OSHDB, see time

  • timeout – custom timeout to limit the processing time in seconds; default: empty

  • types – OSM type(s) ‘node’ and/or ‘way’ and/or ‘relation’ OR simple feature type(s) ‘point’ and/or ‘line’ and/or ‘polygon’ and/or ‘other’; default: all three OSM types

  • values – OSM value(s) given as a list and combined with the ‘AND’ operator; values(n) MUST fit to keys(n); default: empty

Example request:

# How big is the area of farmland in the region Rhein-Neckar?

curl -X GET 'https://api.ohsome.org/v1.0/elements/area?bboxes=8.625,49.3711,8.7334,49.4397&format=json&time=2014-01-01&filter=landuse=farmland%20and%20type:way' -H  'accept: application/json'
# How big is the area of farmland in the region Rhein-Neckar?

curl -X POST 'https://api.ohsome.org/v1.0/elements/area' --data-urlencode 'bboxes=8.625,49.3711,8.7334,49.4397' --data-urlencode  'format=json' --data-urlencode  'time=2014-01-01' --data-urlencode  'filter=landuse=farmland and type:way'
# How big is the area of farmland in the region Rhein-Neckar?

import requests
URL = 'https://api.ohsome.org/v1.0/elements/area'
data = {"bboxes": "8.625,49.3711,8.7334,49.4397", "format": "json", "time": "2014-01-01", "filter": "landuse=farmland and type:way"}
response = requests.post(URL, data=data)
print(response.json())
# How big is the area of farmland in the region Rhein-Neckar?

library(httr)
r <- POST("https://api.ohsome.org/v1.0/elements/area",encode = "form",body = list(bboxes = "8.625,49.3711,8.7334,49.4397",filter = "landuse=farmland and type:way",time = "2014-01-01"))
r

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "timestamp" : "2014-01-01T00:00:00Z",
    "value" : 1.020940258E7
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "timestamp" : "2014-01-01T00:00:00Z",
    "value" : 1.020940258E7
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "timestamp" : "2014-01-01T00:00:00Z",
    "value" : 10209402.58
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "timestamp" : "2014-01-01T00:00:00Z",
    "value" : 1.020940258E7
  } ]
}
POST /elements/(aggregation)/density

Get density of aggregation of OSM elements divided by the total area in square-kilometers.

  • aggregation type: one of area, count, length, perimeter

Query Parameters

Example request:

# What is the density of restaurants with wheelchair access in Heidelberg?

curl -X GET 'https://api.ohsome.org/v1.0/elements/count/density?bboxes=8.625%2C49.3711%2C8.7334%2C49.4397&format=json&filter=amenity=restaurant and wheelchair=yes and type:node&time=2019-05-07' -H  'accept: application/json'
# What is the density of restaurants with wheelchair access in Heidelberg?

curl -X POST 'https://api.ohsome.org/v1.0/elements/count/density' --data-urlencode 'bboxes=8.625,49.3711,8.7334,49.4397' --data-urlencode  'format=json' --data-urlencode  'time=2019-05-07' --data-urlencode  'filter=amenity=restaurant and wheelchair=yes and type:node'
# What is the density of restaurants with wheelchair access in Heidelberg?

import requests
URL = 'https://api.ohsome.org/v1.0/elements/count/density'
data = {"bboxes": "8.625,49.3711,8.7334,49.4397", "format": "json", "time": "2019-05-07", "filter": "amenity=restaurant and wheelchair=yes and type:node"}
response = requests.post(URL, data=data)
# What is the density of restaurants with wheelchair access in Heidelberg?

library(httr)
r <- POST("https://api.ohsome.org/v1.0/elements/count/density",encode = "form",body = list(bboxes = "8.625,49.3711,8.7334,49.4397",filter = "amenity=restaurant and wheelchair=yes and type:node",time = "2019-05-07"))
r

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "timestamp" : "2019-05-07T00:00:00Z",
    "value" : 0.79
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "timestamp" : "2019-05-07T00:00:00Z",
    "value" : 0.79
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "timestamp" : "2019-05-07T00:00:00Z",
    "value" : 0.79
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "timestamp" : "2019-05-07T00:00:00Z",
    "value" : 0.79
  } ]
}
POST /elements/(aggregation)/ratio

Get ratio of OSM elements satisfying filter2 (or keys2, values2, types2) within filter (or keys, values, types).

  • aggregation type: one of area, count, length, perimeter

Query Parameters
  • <other> – see above

  • filter2 – see filter

  • keys2 – see keys

  • types2 – see types

  • values2 – see values

Example request:

# How many oneway streets exist within living_street streets in Heidelberg over time?

curl -X GET 'https://api.ohsome.org/v1.0/elements/length/ratio?bboxes=8.625%2C49.3711%2C8.7334%2C49.4397&format=json&filter=highway=living_street and type:way&filter2=oneway=yes and type:way&time=2016-01-01%2F2018-01-01%2FP1Y' -H  'accept: application/json'
# How many oneway streets exist within living_street streets in Heidelberg over time?

curl -X POST 'https://api.ohsome.org/v1.0/elements/length/ratio' --data-urlencode 'bboxes=8.625,49.3711,8.7334,49.4397' --data-urlencode  'format=json' --data-urlencode  'time=2016-01-01/2018-01-01/P1Y' --data-urlencode  'filter=highway=living_street and type:way' --data-urlencode  'filter2=oneway=yes and type:way'
# How many oneway streets exist within living_street streets in Heidelberg over time?

import requests
URL = 'https://api.ohsome.org/v1.0/elements/length/ratio'
data = {"bboxes": "8.625,49.3711,8.7334,49.4397", "format": "json", "time": "2016-01-01/2018-01-01/P1Y", "filter": "highway=living_street and type:way", "filter2": "oneway=yes and type:way"}
response = requests.post(URL, data=data)
print(response.json())
# How many oneway streets exist within living_street streets in Heidelberg over time?

library(httr)
r <- POST("https://api.ohsome.org/v1.0/elements/length/ratio",encode = "form",body = list(bboxes = "8.625,49.3711,8.7334,49.4397",time = "2016-01-01/2018-01-01/P1Y",filter = "highway=living_street and type:way",filter2 = "oneway=yes and type:way"))
r

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "ratioResult" : [ {
    "timestamp" : "2016-01-01T00:00:00Z",
    "value" : 28660.519999999997,
    "value2" : 177243.99000000002,
    "ratio" : 6.184256
  }, {
    "timestamp" : "2017-01-01T00:00:00Z",
    "value" : 29410.69,
    "value2" : 183803.09,
    "ratio" : 6.249533
  }, {
    "timestamp" : "2018-01-01T00:00:00Z",
    "value" : 30191.93,
    "value2" : 183180.4,
    "ratio" : 6.067197
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "ratioResult" : [ {
    "timestamp" : "2016-01-01T00:00:00Z",
    "value" : 28660.519999999997,
    "value2" : 177243.99000000002,
    "ratio" : 6.184256
  }, {
    "timestamp" : "2017-01-01T00:00:00Z",
    "value" : 29410.69,
    "value2" : 183803.09,
    "ratio" : 6.249533
  }, {
    "timestamp" : "2018-01-01T00:00:00Z",
    "value" : 30191.93,
    "value2" : 183180.4,
    "ratio" : 6.067197
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "ratioResult" : [ {
    "timestamp" : "2016-01-01T00:00:00Z",
    "value" : 28660.519999999997,
    "value2" : 177243.99000000002,
    "ratio" : 6.184256
  }, {
    "timestamp" : "2017-01-01T00:00:00Z",
    "value" : 29410.69,
    "value2" : 183803.09,
    "ratio" : 6.249533
  }, {
    "timestamp" : "2018-01-01T00:00:00Z",
    "value" : 30191.93,
    "value2" : 183180.4,
    "ratio" : 6.067197
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "ratioResult" : [ {
    "timestamp" : "2016-01-01T00:00:00Z",
    "value" : 28660.519999999997,
    "value2" : 177243.99000000002,
    "ratio" : 6.184256
  }, {
    "timestamp" : "2017-01-01T00:00:00Z",
    "value" : 29410.69,
    "value2" : 183803.09,
    "ratio" : 6.249533
  }, {
    "timestamp" : "2018-01-01T00:00:00Z",
    "value" : 30191.93,
    "value2" : 183180.4,
    "ratio" : 6.067197
  } ]
}
POST /elements/(aggregation)/groupBy/(groupType)

Get aggregation of OSM elements grouped by groupType.

  • aggregation type: one of area, count, length, perimeter

  • grouping type: one of boundary, key, tag, type.

Query Parameters

Note

For groupBy/key and groupBy/tag, there are additional resource-specific parameters, which you can find at groupBy.

Example request:

# How often information about the roof of buildings is present?

curl -X GET 'https://api.ohsome.org/v1.0/elements/count/groupBy/key?bboxes=Heidelberg:8.625%2C49.3711%2C8.7334%2C49.4397&format=json&time=2018-01-01&filter=building=* and type:way&groupByKeys=building:roof,building:roof:colour' -H  'accept: application/json'
# How often information about the roof of buildings is present?

curl -X POST 'https://api.ohsome.org/v1.0/elements/count/groupBy/key' --data-urlencode 'bboxes=Heidelberg:8.625,49.3711,8.7334,49.4397' --data-urlencode  'format=json' --data-urlencode  'time=2018-01-01' --data-urlencode  'groupByKeys=building:roof,building:roof:colour'  --data-urlencode  'filter=building=* and type:way'
# How often information about the roof of buildings is present?

import requests
URL = 'https://api.ohsome.org/v1.0/elements/count/groupBy/key'
data = {"bboxes": "8.625,49.3711,8.7334,49.4397", "format": "json", "time": "2018-01-01", "filter": "building=* and type:way", "groupByKeys": "building:roof,building:roof:colour"}
response = requests.post(URL, data=data)
print(response.json())
# How often information about the roof of buildings is present?

library(httr)
  r <- POST("https://api.ohsome.org/v1.0/elements/count/groupBy/key",encode = "form",body = list(bboxes = "8.625,49.3711,8.7334,49.4397",filter = "building=* and type:way",time = "2018-01-01",groupByKeys = "building:roof,building:roof:colour"))
  r

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "groupByResult" : [ {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 23225.0
    } ],
    "groupByObject" : "remainder"
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1418.0
    } ],
    "groupByObject" : "building:roof"
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1178.0
    } ],
    "groupByObject" : "building:roof:colour"
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "groupByResult" : [ {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 23225.0
    } ],
    "groupByObject" : "remainder"
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1418.0
    } ],
    "groupByObject" : "building:roof"
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1178.0
    } ],
    "groupByObject" : "building:roof:colour"
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "groupByResult" : [ {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 23225.0
    } ],
    "groupByObject" : "remainder"
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1418.0
    } ],
    "groupByObject" : "building:roof"
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1178.0
    } ],
    "groupByObject" : "building:roof:colour"
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "groupByResult" : [ {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 23225.0
    } ],
    "groupByObject" : "remainder"
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1418.0
    } ],
    "groupByObject" : "building:roof"
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1178.0
    } ],
    "groupByObject" : "building:roof:colour"
  } ]
}
POST /elements/(aggregation)/density/groupBy/(groupType)

Get density of aggregation of OSM elements grouped by groupType.

  • aggregation type: one of area, count, length, perimeter

  • grouping type: see above - Same as for aggregation of OSM elements grouped by groupType but without groupBy/key.

POST /elements/(aggregation)/groupBy/boundary/groupBy/tag

Get aggregation of OSM elements grouped by boundary and tag.

  • aggregation type: one of area, count, length, perimeter

Query Parameters
  • <other> – see above

  • groupByKey – see groupBy

  • groupByValues – see groupBy

Example request:

# Compare length of different types of streets for two or more regions.

curl -X GET 'https://api.ohsome.org/v1.0/elements/length/groupBy/boundary/groupBy/tag?bboxes=Heidelberg:8.625%2C49.3711%2C8.7334%2C49.4397|Plankstadt:8.5799,49.3872,8.6015,49.4011&format=json&groupByKey=highway&time=2018-01-01&groupByValues=primary,secondary,tertiary&filter=type:way' -H  'accept: application/json'
# Compare length of different types of streets for two or more regions.

curl -X POST 'https://api.ohsome.org/v1.0/elements/length/groupBy/boundary/groupBy/tag' --data-urlencode 'bboxes=Heidelberg:8.625,49.3711,8.7334,49.4397|Plankstadt:8.5799,49.3872,8.6015,49.4011' --data-urlencode  'format=json' --data-urlencode  'time=2018-01-01' --data-urlencode  'filter=type:way' --data-urlencode  'groupByKey=highway'  --data-urlencode  'groupByValues=primary,secondary,tertiary'
# Compare length of different types of streets for two or more regions.

import requests
URL = 'https://api.ohsome.org/v1.0/elements/length/groupBy/boundary/groupBy/tag'
data = {"bboxes": "Heidelberg:8.625,49.3711,8.7334,49.4397|Plankstadt:8.5799,49.3872,8.6015,49.4011", "format": "json", "time": "2018-01-01", "filter": "type:way", "groupByKey": "highway", "groupByValues": "primary,secondary,tertiary"}
response = requests.post(URL, data=data)
print(response.json())
# Compare length of different types of streets for two or more regions.

library(httr)
r <- POST("https://api.ohsome.org/v1.0/elements/length/groupBy/boundary/groupBy/tag",encode = "form",body = list(bboxes = "Heidelberg:8.625,49.3711,8.7334,49.4397|Plankstadt:8.5799,49.3872,8.6015,49.4011",groupByKey = "highway",time = "2018-01-01",filter = "type:way",groupByValues = "primary,secondary,tertiary"))
r

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "groupByResult" : [ {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1650245.08
    } ],
    "groupByObject" : [ "Heidelberg", "remainder" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 48637.96
    } ],
    "groupByObject" : [ "Heidelberg", "highway=tertiary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 29114.72
    } ],
    "groupByObject" : [ "Heidelberg", "highway=secondary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 35297.95
    } ],
    "groupByObject" : [ "Heidelberg", "highway=primary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 56493.26
    } ],
    "groupByObject" : [ "Plankstadt", "remainder" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 3399.22
    } ],
    "groupByObject" : [ "Plankstadt", "highway=tertiary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 954.7
    } ],
    "groupByObject" : [ "Plankstadt", "highway=secondary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 0.0
    } ],
    "groupByObject" : [ "Plankstadt", "highway=primary" ]
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "groupByResult" : [ {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1650245.08
    } ],
    "groupByObject" : [ "Heidelberg", "remainder" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 48637.96
    } ],
    "groupByObject" : [ "Heidelberg", "highway=tertiary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 29114.72
    } ],
    "groupByObject" : [ "Heidelberg", "highway=secondary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 35297.95
    } ],
    "groupByObject" : [ "Heidelberg", "highway=primary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 56493.26
    } ],
    "groupByObject" : [ "Plankstadt", "remainder" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 3399.22
    } ],
    "groupByObject" : [ "Plankstadt", "highway=tertiary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 954.7
    } ],
    "groupByObject" : [ "Plankstadt", "highway=secondary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 0.0
    } ],
    "groupByObject" : [ "Plankstadt", "highway=primary" ]
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "groupByResult" : [ {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1650245.08
    } ],
    "groupByObject" : [ "Heidelberg", "remainder" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 48637.96
    } ],
    "groupByObject" : [ "Heidelberg", "highway=tertiary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 29114.72
    } ],
    "groupByObject" : [ "Heidelberg", "highway=secondary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 35297.95
    } ],
    "groupByObject" : [ "Heidelberg", "highway=primary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 56493.26
    } ],
    "groupByObject" : [ "Plankstadt", "remainder" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 3399.22
    } ],
    "groupByObject" : [ "Plankstadt", "highway=tertiary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 954.7
    } ],
    "groupByObject" : [ "Plankstadt", "highway=secondary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 0.0
    } ],
    "groupByObject" : [ "Plankstadt", "highway=primary" ]
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "groupByResult" : [ {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 1650245.08
    } ],
    "groupByObject" : [ "Heidelberg", "remainder" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 48637.96
    } ],
    "groupByObject" : [ "Heidelberg", "highway=tertiary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 29114.72
    } ],
    "groupByObject" : [ "Heidelberg", "highway=secondary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 35297.95
    } ],
    "groupByObject" : [ "Heidelberg", "highway=primary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 56493.26
    } ],
    "groupByObject" : [ "Plankstadt", "remainder" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 3399.22
    } ],
    "groupByObject" : [ "Plankstadt", "highway=tertiary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 954.7
    } ],
    "groupByObject" : [ "Plankstadt", "highway=secondary" ]
  }, {
    "result" : [ {
      "timestamp" : "2018-01-01T00:00:00Z",
      "value" : 0.0
    } ],
    "groupByObject" : [ "Plankstadt", "highway=primary" ]
  } ]
}
POST /elements/(aggregation)/density/groupBy/boundary/groupBy/tag

Get density of aggregation of OSM elements grouped by boundary and tag.

  • aggregation type: same as for /elements/(aggregation)/groupBy/boundary/groupBy/tag.

Users Aggregation Endpoints

POST /users/count

Compute data aggregation functions on users. Possbile endpoints:

  • /count

  • /count/groupBy/(groupType)

  • /count/density

  • /count/density/groupBy/(boundary or tag or type)

Query Parameters
Parameters

Example request:

# Show number of users editing buildings before, during and after Nepal earthquake 2015.

curl -X GET 'https://api.ohsome.org/v1.0/users/count?bboxes=82.3055%2C6.7576%2C87.4663%2C28.7025&format=json&filter=building=* and type:way&time=2015-03-01/2015-08-01/P1M' -H  'accept: application/json'
# Show number of users editing buildings before, during and after Nepal earthquake 2015.

curl -X POST 'https://api.ohsome.org/v1.0/users/count' --data-urlencode 'bboxes=82.3055,6.7576,87.4663,28.7025' --data-urlencode  'format=json' --data-urlencode  'time=2015-03-01/2015-08-01/P1M' --data-urlencode  'filter=building=* and type:way'
# Show number of users editing buildings before, during and after Nepal earthquake 2015.

import requests
URL = 'https://api.ohsome.org/v1.0/users/count'
data = {"bboxes": "82.3055,6.7576,87.4663,28.7025", "format": "json", "time": "2015-03-01/2015-08-01/P1M", "filter": "building=* and type:way"}
response = requests.post(URL, data=data)
print(response.json())
# Show number of users editing buildings before, during and after Nepal earthquake 2015.

library(httr)
r <- POST("https://api.ohsome.org/v1.0/users/count",encode = "form",body = list(bboxes = "82.3055,6.7576,87.4663,28.7025",filter = "building=* and type:way",time = "2015-03-01/2015-08-01/P1M"))
r

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "fromTimestamp" : "2015-03-01T00:00:00Z",
    "toTimestamp" : "2015-04-01T00:00:00Z",
    "value" : 97.0
  }, {
    "fromTimestamp" : "2015-04-01T00:00:00Z",
    "toTimestamp" : "2015-05-01T00:00:00Z",
    "value" : 3490.0
  }, {
    "fromTimestamp" : "2015-05-01T00:00:00Z",
    "toTimestamp" : "2015-06-01T00:00:00Z",
    "value" : 3102.0
  }, {
    "fromTimestamp" : "2015-06-01T00:00:00Z",
    "toTimestamp" : "2015-07-01T00:00:00Z",
    "value" : 477.0
  }, {
    "fromTimestamp" : "2015-07-01T00:00:00Z",
    "toTimestamp" : "2015-08-01T00:00:00Z",
    "value" : 185.0
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "fromTimestamp" : "2015-03-01T00:00:00Z",
    "toTimestamp" : "2015-04-01T00:00:00Z",
    "value" : 97.0
  }, {
    "fromTimestamp" : "2015-04-01T00:00:00Z",
    "toTimestamp" : "2015-05-01T00:00:00Z",
    "value" : 3490.0
  }, {
    "fromTimestamp" : "2015-05-01T00:00:00Z",
    "toTimestamp" : "2015-06-01T00:00:00Z",
    "value" : 3102.0
  }, {
    "fromTimestamp" : "2015-06-01T00:00:00Z",
    "toTimestamp" : "2015-07-01T00:00:00Z",
    "value" : 477.0
  }, {
    "fromTimestamp" : "2015-07-01T00:00:00Z",
    "toTimestamp" : "2015-08-01T00:00:00Z",
    "value" : 185.0
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "fromTimestamp" : "2015-03-01T00:00:00Z",
    "toTimestamp" : "2015-04-01T00:00:00Z",
    "value" : 97.0
  }, {
    "fromTimestamp" : "2015-04-01T00:00:00Z",
    "toTimestamp" : "2015-05-01T00:00:00Z",
    "value" : 3490.0
  }, {
    "fromTimestamp" : "2015-05-01T00:00:00Z",
    "toTimestamp" : "2015-06-01T00:00:00Z",
    "value" : 3102.0
  }, {
    "fromTimestamp" : "2015-06-01T00:00:00Z",
    "toTimestamp" : "2015-07-01T00:00:00Z",
    "value" : 477.0
  }, {
    "fromTimestamp" : "2015-07-01T00:00:00Z",
    "toTimestamp" : "2015-08-01T00:00:00Z",
    "value" : 185.0
  } ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "result" : [ {
    "fromTimestamp" : "2015-03-01T00:00:00Z",
    "toTimestamp" : "2015-04-01T00:00:00Z",
    "value" : 97.0
  }, {
    "fromTimestamp" : "2015-04-01T00:00:00Z",
    "toTimestamp" : "2015-05-01T00:00:00Z",
    "value" : 3490.0
  }, {
    "fromTimestamp" : "2015-05-01T00:00:00Z",
    "toTimestamp" : "2015-06-01T00:00:00Z",
    "value" : 3102.0
  }, {
    "fromTimestamp" : "2015-06-01T00:00:00Z",
    "toTimestamp" : "2015-07-01T00:00:00Z",
    "value" : 477.0
  }, {
    "fromTimestamp" : "2015-07-01T00:00:00Z",
    "toTimestamp" : "2015-08-01T00:00:00Z",
    "value" : 185.0
  } ]
}

Extraction Endpoints

POST /elements/(geometryType)

Get snapshots of OSM data having the given geometryType (bbox, centroid, or geometry)

Query Parameters
  • time – required; format same as described in time

  • properties – property groups added to each OSM element: ‘tags’ and/or ‘metadata’ and/or ‘unclipped’; default: empty

  • <other> – see above

Note

The extraction endpoints always return a .geojson file.

Example request:

# Get all the bike rental stations in Heidelberg.

curl -X GET 'https://api.ohsome.org/v1.0/elements/geometry?bboxes=8.625%2C49.3711%2C8.7334%2C49.4397&filter=amenity=bicycle_rental and type:node&time=2019-09-01' -H  'accept: application/json'
# Get all the bike rental stations in Heidelberg.

curl -X POST 'https://api.ohsome.org/v1.0/elements/geometry' --data-urlencode 'bboxes=8.625,49.3711,8.7334,49.4397' --data-urlencode  'time=2019-09-01' --data-urlencode  'filter=amenity=bicycle_rental and type:node'
# Get all the bike rental stations in Heidelberg.

import requests
URL = 'https://api.ohsome.org/v1.0/elements/geometry'
data = {"bboxes": "8.625,49.3711,8.7334,49.4397", "time": "2019-09-01", "filter": "amenity=bicycle_rental and type:node"}
response = requests.post(URL, data=data)
print(response.json())
# Get all the bike rental stations in Heidelberg.

library(httr)
r <- POST("https://api.ohsome.org/v1.0/elements/geometry",encode = "form",body = list(bboxes = "8.625,49.3711,8.7334,49.4397",filter = "amenity=bicycle_rental and type:node",time = "2019-09-01"))
r

Example response:

file ohsome.geojson
file ohsome.geojson
file ohsome.geojson
file ohsome.geojson
POST /elementsFullHistory/(geometryType)

Get the full history of OSM data having the given geometryType. This endpoint has the same geometry types as the /elements endpoint.

Query Parameters
  • time – required; can only consist of two ISO-8601 conform timestrings defining an interval; no default value

  • properties – property groups added to each OSM element: ‘tags’ and/or ‘metadata’ and/or ‘unclipped’; default: empty

  • <other> – see above

Example request:

# Extract the modifications of the blown up tower of the heidelberg castle over time

curl -X GET 'https://api.ohsome.org/v1.0/elementsFullHistory/geometry?bboxes=8.7137%2C49.4096%2C8.717%2C49.4119&filter=name=Krautturm and type:way&time=2008-01-01%2C2016-01-01' -H  'accept: application/json'
# Extract the modifications of the blown up tower of the heidelberg castle over time

curl -X POST 'https://api.ohsome.org/v1.0/elementsFullHistory/geometry' --data-urlencode 'bboxes=8.7137,49.4096,8.717,49.4119' --data-urlencode  'time=2008-01-01,2016-01-01' --data-urlencode  'filter=name=Krautturm and type:way'
# Extract the modifications of the blown up tower of the heidelberg castle over time

import requests
URL = 'https://api.ohsome.org/v1.0/elementsFullHistory/geometry'
data = {"bboxes": "8.7137,49.4096,8.717,49.4119", "time": "2008-01-01,2016-01-01", "filter": "name=Krautturm and type:way"}
response = requests.post(URL, data=data)
print(response.json())
# Extract the modifications of the blown up tower of the heidelberg castle over time

library(httr)
r <- POST("https://api.ohsome.org/v1.0/elementsFullHistory/geometry",encode = "form",body = list(bboxes = "8.7137,49.4096,8.717,49.4119",time = "2008-01-01,2016-01-01",filter = "name=Krautturm and type:way"))
r

Note

The following example responses only show parts of the returned .geojson file.

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "type" : "FeatureCollection",
  "features" : [{
    "type" : "Feature",
    "geometry" : {
      "type" : "Polygon",
      "coordinates" : [
        [
          [
            8.7160104,
            49.4102861
          ],
           ...
           [
            8.7160104,
            49.4102861
          ]
        ]
      ]
    },
    "properties" : {
      "@osmId" : "way/24885641",
      "@validFrom" : "2008-06-15T05:25:25Z",
      "@validTo" : "2008-08-09T14:46:28Z",
      "name" : "Krautturm"
    }
  },
  ...
  ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "type" : "FeatureCollection",
  "features" : [{
    "type" : "Feature",
    "geometry" : {
      "type" : "Polygon",
      "coordinates" : [
        [
          [
            8.7160104,
            49.4102861
          ],
           ...
           [
            8.7160104,
            49.4102861
          ]
        ]
      ]
    },
    "properties" : {
      "@osmId" : "way/24885641",
      "@validFrom" : "2008-06-15T05:25:25Z",
      "@validTo" : "2008-08-09T14:46:28Z",
      "name" : "Krautturm"
    }
  },
  ...
  ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "type" : "FeatureCollection",
  "features" : [{
    "type" : "Feature",
    "geometry" : {
      "type" : "Polygon",
      "coordinates" : [
        [
          [
            8.7160104,
            49.4102861
          ],
           ...
           [
            8.7160104,
            49.4102861
          ]
        ]
      ]
    },
    "properties" : {
      "@osmId" : "way/24885641",
      "@validFrom" : "2008-06-15T05:25:25Z",
      "@validTo" : "2008-08-09T14:46:28Z",
      "name" : "Krautturm"
    }
  },
  ...
  ]
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "type" : "FeatureCollection",
  "features" : [{
    "type" : "Feature",
    "geometry" : {
      "type" : "Polygon",
      "coordinates" : [
        [
          [
            8.7160104,
            49.4102861
          ],
           ...
           [
            8.7160104,
            49.4102861
          ]
        ]
      ]
    },
    "properties" : {
      "@osmId" : "way/24885641",
      "@validFrom" : "2008-06-15T05:25:25Z",
      "@validTo" : "2008-08-09T14:46:28Z",
      "name" : "Krautturm"
    }
  },
  ...
  ]
}

Metadata Endpoint

GET /metadata

Get metadata of the underlying OSHDB data. Does not consume any parameters. Only GET requests.

Example request:

# Get metadata of the underlying OSHDB data

curl -X GET 'https://api.ohsome.org/v1.0/metadata'
# Get metadata of the underlying OSHDB data

import requests
URL = 'https://api.ohsome.org/v1.0/metadata'
response = requests.get(URL)
print(response)
# Get metadata of the underlying OSHDB data

library(httr)
r <- GET("https://api.ohsome.org/v1.0/metadata",encode = "form")
r

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "extractRegion" : {
    "spatialExtent" : {
      "type" : "Polygon",
      "coordinates" : [ [ [ -180.0, -90.0 ], [ 180.0, -90.0 ], [ 180.0, 90.0 ], [ -180.0, 90.0 ], [ -180.0, -90.0 ] ] ]
    },
    "temporalExtent" : {
      "fromTimestamp" : "2007-10-08T00:00:00Z",
      "toTimestamp" : "2020-02-12T23:00:00Z"
    },
    "replicationSequenceNumber" : 65032
  }
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "extractRegion" : {
    "spatialExtent" : {
      "type" : "Polygon",
      "coordinates" : [ [ [ -180.0, -90.0 ], [ 180.0, -90.0 ], [ 180.0, 90.0 ], [ -180.0, 90.0 ], [ -180.0, -90.0 ] ] ]
    },
    "temporalExtent" : {
      "fromTimestamp" : "2007-10-08T00:00:00Z",
      "toTimestamp" : "2020-02-12T23:00:00Z"
    },
    "replicationSequenceNumber" : 65032
  }
}
{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.0",
  "extractRegion" : {
    "spatialExtent" : {
      "type" : "Polygon",
      "coordinates" : [ [ [ -180.0, -90.0 ], [ 180.0, -90.0 ], [ 180.0, 90.0 ], [ -180.0, 90.0 ], [ -180.0, -90.0 ] ] ]
    },
    "temporalExtent" : {
      "fromTimestamp" : "2007-10-08T00:00:00Z",
      "toTimestamp" : "2020-02-12T23:00:00Z"
    },
    "replicationSequenceNumber" : 65032
  }
}