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 parameters types, keys and values is not recommended as they are deprecated. Please use the filter parameter for your requests.

Elements Aggregation

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

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

  • 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’

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

  • timeout – custom timeout to limit the processing time in seconds; default: dependent on server settings, retrievable via the /metadata request

  • types – Deprecated! Use filter parameter instead! Old parameter which allowed to specify 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

  • keys – Deprecated! Use filter parameter instead! Old parameter which allowed to specify OSM key(s) given as a list and combined with the ‘AND’ operator; default: empty

  • values – Deprecated! Use filter parameter instead! Old parameter which allowed to specify 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/elements/area?bboxes=8.625%2C49.3711%2C8.7334%2C49.4397&format=json&time=2014-01-01&filter=landuse%3Dfarmland%20and%20type%3Away'

Example response:

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

Get density of aggregation of OSM elements in the total query area per 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/elements/count/density?bboxes=8.625%2C49.3711%2C8.7334%2C49.4397&format=json&filter=amenity%3Drestaurant%20and%20wheelchair%3Dyes%20and%20type%3Anode&time=2019-05-07'

Example response:

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

Get ratio of OSM elements satisfying filter2 to elements satisfying filter.

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

Query Parameters
  • <other> – see above

  • filter2 – see filter

  • keys2 – Deprecated! see filter2

  • types2 – Deprecated! use filter2

  • values2 – Deprecated! see filter2

Example request:

How many oneway streets exist within living_street streets in Heidelberg over time? And how many of them are oneway streets?

curl -X GET 'https://api.ohsome.org/v1/elements/length/ratio?bboxes=8.625%2C49.3711%2C8.7334%2C49.4397&format=json&filter=highway%3Dliving_street%20and%20type%3Away&filter2=highway%3Dliving_street%20and%20oneway%3Dyes%20and%20type%3Away&time=2016-01-01%2F2018-01-01%2FP1Y'

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.4.2",
  "ratioResult" : [ {
    "timestamp" : "2016-01-01T00:00:00Z",
    "value" : 28660.519999999997,
    "value2" : 7079.26,
    "ratio" : 0.247004
  }, {
    "timestamp" : "2017-01-01T00:00:00Z",
    "value" : 29410.69,
    "value2" : 7025.94,
    "ratio" : 0.238891
  }, {
    "timestamp" : "2018-01-01T00:00:00Z",
    "value" : 30191.93,
    "value2" : 6729.34,
    "ratio" : 0.222885
  } ]
}
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/elements/count/groupBy/key?bboxes=Heidelberg:8.625%2C49.3711%2C8.7334%2C49.4397&format=json&time=2018-01-01&filter=building%3D*%20and%20type%3Away&groupByKeys=building%3Aroof%2Cbuilding%3Aroof%3Acolour'

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.4.2",
  "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/elements/length/groupBy/boundary/groupBy/tag?bboxes=Heidelberg%3A8.625%2C49.3711%2C8.7334%2C49.4397%7CPlankstadt%3A8.5799%2C49.3872%2C8.6015%2C49.4011&format=json&groupByKey=highway&time=2018-01-01&groupByValues=primary%2Csecondary%2Ctertiary&filter=type%3Away'

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.4.2",
  "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

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/users/count?bboxes=82.3055%2C6.7576%2C87.4663%2C28.7025&format=json&filter=building%3D*%20and%20type%3Away&time=2015-03-01%2F2015-08-01%2FP1M'

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.4.2",
  "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
  } ]
}

Contributions Aggregation

POST /contributions/count

Get the count of the contributions provided to the OSM data. This endpoint does not support the deprecated types, keys, values parameters.

Note

The /contributions/count endpoint is a new feature that is in the experimental status, meaning it is still under internal evaluation and might be subject to changes in the upcoming minor or patch releases.

Example request:

Number of contributions to the building ‘Stadthalle Heidelberg’ between 2010 and 2020.

curl -X GET 'https://api.ohsome.org/v1/contributions/count?bboxes=8.699053,49.411842,8.701311,49.412893&filter=id:way/140112810&time=2010-01-01,2020-01-01'

Example response:

{
  "attribution":{
    "url":"https://ohsome.org/copyrights",
    "text":"© OpenStreetMap contributors"
  },
  "apiVersion":"1.4.2",
  "result":[
    {
      "fromTimestamp":"2010-01-01T00:00:00Z",
      "toTimestamp":"2020-01-01T00:00:00Z",
      "value":15.0
    }
  ]
}
POST /contributions/count/density

Get the density of the count of contributions in the total query area in counts per square-kilometers. This endpoint does not support the deprecated types, keys, values parameters.

Example request:

Density of contributions to shops within the oldtown area of Heidelberg between 2012 and 2016.

curl -X GET 'https://api.ohsome.org/v1/contributions/count/density?bboxes=8.69282,49.40766,8.71673,49.4133&filter=shop=*%20and%20type:node&time=2012-01-01,2016-01-01'

Example response:

{
  "attribution":{
    "url":"https://ohsome.org/copyrights",
    "text":"© OpenStreetMap contributors"
  },
  "apiVersion":"1.4.2",
  "result":[
    {
      "fromTimestamp":"2012-01-01T00:00:00Z",
      "toTimestamp":"2016-01-01T00:00:00Z",
      "value":417.13
    }
  ]
}

Elements Extraction

POST /elements/(geometryType)

Get the state of OSM data at the given timestamp(s) as a GeoJSON feature collection where object geometries are returned as the given geometryType (geometry, bbox, or centroid).

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

  • properties – specifies what properties should be included for each feature representing an OSM element: ‘tags’ and/or ‘metadata’; multiple values can be delimited by commas; default: empty

  • clipGeometry – boolean operator to specify whether the returned geometries of the features should be clipped to the query’s spatial boundary (‘true’), or not (‘false’); default: ‘true’

  • <other> – see above (except format)

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/elements/geometry?bboxes=8.625%2C49.3711%2C8.7334%2C49.4397&filter=amenity%3Dbicycle_rental%20and%20type%3Anode&time=2019-09-01'

Example response:

file ohsome.geojson
POST /elementsFullHistory/(geometryType)

Get the full history of OSM data as a GeoJSON feature collection. All changes to matching OSM features are included with corresponding validFrom and validTo timestamps. This endpoint supports the same geometryType options as the /elements endpoint.

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

  • properties – same as for generic-extraction

  • clipGeometry – same as for generic-extraction

  • <other> – see above (except format)

Example request:

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

curl -X GET 'https://api.ohsome.org/v1/elementsFullHistory/geometry?bboxes=8.7137%2C49.4096%2C8.717%2C49.4119&filter=name%3DKrautturm%20and%20type%3Away&time=2008-01-01%2C2016-01-01'

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.4.2",
  "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"
    }
  },
  ...
  ]
}

Contributions Extraction

POST /contributions/(geometryType)

Get the contributions provided to the OSM data. This endpoint does not support the deprecated types, keys, values parameters. It uses the same geometryType options as the /elements and /elementsFullHistory endpoints.

Example request:

Get the changes of pharmacies with opening hours in a certain area of Heidelberg in times of COVID-19

curl -X GET 'https://api.ohsome.org/v1/contributions/geometry?bboxes=8.6720%2C49.3988%2C8.7026%2C49.4274&filter=amenity=pharmacy%20and%20opening_hours=*%20and%20type:node&time=2020-02-01%2C2020-06-29&showMetadata=yes&properties=metadata%2Ctags&clipGeometry=false'

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.4.2",
  "metadata" : {
    "description" : "Latest contributions as GeoJSON features.",
    "requestUrl" : "https://api.ohsome.org/v1/contributions/latest/geometry?bboxes=8.6720,49.3988,8.7026,49.4274&filter=amenity=pharmacy%20and%20opening_hours=*%20and%20type:node&time=2020-02-01,2020-06-29&showMetadata=yes&properties=metadata,tags&clipGeometry=false"
  },
  "type" : "FeatureCollection",
  "features" : [{
    "type" : "Feature",
    "geometry" : {
      "type" : "Point",
      "coordinates" : [
        8.6902451,
        49.4080159
      ]
    },
    "properties" : {
      "@changesetId" : 83099383,
      "@osmId" : "node/323191854",
      "@osmType" : "NODE",
      "@tagChange" : true,
      "@timestamp" : "2020-04-05T13:32:50Z",
      "@version" : 8,
      "addr:city" : "Heidelberg",
      "addr:housenumber" : "24",
      "addr:postcode" : "69115",
      "addr:street" : "Poststraße",
      "amenity" : "pharmacy",
      "contact:email" : "aesculap-heidelberg@web.de",
      "contact:fax" : "+49 6221 163746",
      "contact:phone" : "+49 6221 27634",
      "dispensing" : "yes",
      "healthcare" : "pharmacy",
      "name" : "Aesculap Apotheke",
      "opening_hours" : "Mo-Fr 08:30-18:30; Sa 09:00-13:00",
      "operator" : "Stefan Wowra",
      "website" : "https://aesculap-heidelberg.de",
      "wheelchair" : "yes"
    }
  }, { ...
  }, {
    "type" : "Feature",
    "geometry" : {
      "type" : "Point",
      "coordinates" : [
        8.6922106,
        49.4103048
      ]
    },
    "properties" : {
      "@changesetId" : 83099383,
      "@osmId" : "node/5400804545",
      "@osmType" : "NODE",
      "@tagChange" : true,
      "@timestamp" : "2020-04-05T13:32:50Z",
      "@version" : 2,
      "amenity" : "pharmacy",
      "dispensing" : "yes",
      "fax" : "+49 6221 9831332",
      "healthcare" : "pharmacy",
      "name" : "ATOS-Apotheke",
      "opening_hours" : "Mo-Fr 08:30-18:30; Sa 09:00-14:00",
      "phone" : "+49 6221 9831331",
      "website" : "http://www.atos-apotheke.de",
      "wheelchair" : "yes"
    }
  }]
}
POST /contributions/latest/(geometryType)

Get the the latest state of the contributions provided to the OSM data. This endpoint does not support the deprecated types, keys, values parameters. It uses the same geometryType options as the /elements and /elementsFullHistory endpoints.

Example request:

Get the latest change of constructions in a certain area of the Bahnstadt in Heidelberg

curl -X GET 'https://api.ohsome.org/v1/contributions/latest/geometry?bboxes=8.6644%2C49.4010%2C8.6663%2C49.4027&filter=landuse=construction%20and%20type:way&time=2014-07-01%2C2020-06-29&showMetadata=yes&properties=metadata%2Ctags&clipGeometry=false'

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.4.2",
  "metadata" : {
    "description" : "Latest contributions as GeoJSON features.",
    "requestUrl" : "https://api.ohsome.org/v1/contributions/latest/geometry?bboxes=8.6644159,49.401099,8.6663353,49.4027195&filter=landuse=construction%20and%20type:way&time=2020-06-29,2014-07-01&showMetadata=yes&properties=metadata,tags&clipGeometry=false"
  },
  "type" : "FeatureCollection",
  "features" : [{
    "type" : "Feature",
    "geometry" : {
      "type" : "Polygon",
      "coordinates" : [
        [
          [
            8.6654314,
            49.4026779
          ], ...
    },
    "properties" : {
      "@changesetId" : 85604249,
      "@geometryChange" : true,
      "@osmId" : "way/795435536",
      "@osmType" : "WAY",
      "@timestamp" : "2020-05-22T10:22:53Z",
      "@version" : 3,
      "landuse" : "construction"
    }
  }, {
    "type" : "Feature",
    "geometry" : null,
    "properties" : {
      "@changesetId" : 51902131,
      "@deletion" : true,
      "@osmId" : "way/135635599",
      "@osmType" : "WAY",
      "@timestamp" : "2017-09-10T09:22:03Z",
      "@version" : 9
    }
  }]
}

Metadata

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/metadata'

Example response:

{
  "attribution" : {
    "url" : "https://ohsome.org/copyrights",
    "text" : "© OpenStreetMap contributors"
  },
  "apiVersion" : "1.4.2",
  "timeout": 600.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
  }
}