Class: OverpassFrontend

OverpassFrontend(url, options)

A connection to an Overpass API Server or an OpenStreetMap file

Constructor

new OverpassFrontend(url, options)

Parameters:
Name Type Description
url string The URL of the API, e.g. 'https://overpass-api.de/api/'. If you omit the protocol, it will use the protocol which is in use for the current page (or https: on nodejs): '//overpass-api.de/api/'. If the url ends in .json, .osm or .osm.bz2 it will load this OpenStreetMap file and use the data from there.
options object Options
Properties
Name Type Attributes Default Description
count number <optional>
 0 Only return a maximum of count items. If count=0, no limit is used (default).
effortPerRequest number <optional>
 1000 To avoid huge requests to the Overpass API, the request will be split into smaller chunks. This value defines, how many objects will be requested per API call (for get() calls see effortNode, effortWay, effortRelation, e.g. up to 1000 nodes or 250 ways or (500 nodes and 125 ways) at default values; for BBoxQuery() calls the setting will be divided by 4).
effortNode number <optional>
 1 The effort for request a node. Default: 1.
effortWay number <optional>
 4 The effort for request a way.
effortRelation number <optional>
 64 The effort for request a relation.
effortBBoxFeature number <optional>
 4 The effort for requesting an item in a BboxQuery.
timeGap number <optional>
 10 A short time gap between two requests to the Overpass API (milliseconds).
timeGap429 number <optional>
 500 A longer time gap after a 429 response from Overpass API (milliseconds).
timeGap429Exp number <optional>
 3 If we keep getting 429 responses, increase the time exponentially with the specified factor (e.g. 2: 500ms, 1000ms, 2000ms, ...; 3: 500ms, 1500ms, 4500ms, ...)
loadChunkSize number <optional>
 1000 When loading a file (instead connecting to an Overpass URL) load elements in chunks of n items.
Properties:
Name Type Default Description
hasStretchLon180 boolean false Are there any map features in the cache which stretch over lon=180/-180?
Source:

Methods

BBoxQuery(query, bounds, options, featureCallback, finalCallback) → {RequestBBox}

Parameters:
Name Type Description
query string Query for requesting objects from Overpass API, e.g. "node[amenity=restaurant]" or "(node[amenity];way[highway~'^(primary|secondary)$];)". See Filter for details.
bounds BoundingBox | GeoJSON Boundaries where to load objects, can be a BoundingBox object, Leaflet Bounds object (e.g. from map.getBounds()) or a GeoJSON Polygon/Multipolygon.
options object
Properties
Name Type Attributes Default Description
limit number <optional>
 0 Limit count of results. If 0, no limit will be used.
priority number <optional>
 0 Priority for loading these objects. The lower the sooner they will be requested.
sort boolean | string <optional>
 false If false, it will be called as soon as the features are availabe (e.g. immediately when cached).
properties bit_array <optional>
 Which properties of the features should be downloaded: OVERPASS_ID_ONLY, OVERPASS_BBOX, OVERPASS_TAGS, OVERPASS_GEOM, OVERPASS_META. Combine by binary OR: ``OVERPASS_ID | OVERPASS_BBOX``. Default: OverpassFrontend.TAGS | OverpassFrontend.MEMBERS | OverpassFrontend.BBOX
split number <optional>
 0 If more than 'split' elements would be returned, split into several smaller requests, with 'split' elements each. Default: 0 (do not split)
members boolean <optional>
 false Query relation members of. Default: false
memberCallback function <optional>
 For every member, call this callback function. (Requires options.members=true)
memberProperties bit_array <optional>
 Which properties should be loaded for the members. Default: OverpassFrontend.TAGS | OverpassFrontend.MEMBERS | OverpassFrontend.BBOX
memberBounds BoundingBox | GeoJSON <optional>
 Only return members which intersect these bounds. Boundaries is a BoundingBox, or a Leaflet Bounds object (e.g. from map.getBounds()) or a GeoJSON Polygon/Multipolygon.
memberSplit number <optional>
 0 If more than 'memberSplit' member elements would be returned, split into smaller requests (see 'split'). 0 = do not split.
filter string | Filter <optional>
 Additional filter.
noCacheQuery boolean <optional>
 false If true, the local cache will not be queried
featureCallback function Will be called for each matching object. Will be passed: 1. err (if an error occured, otherwise null), 2. the object or null.
finalCallback function Will be called after the last feature. Will be passed: 1. err (if an error occured, otherwise null).
Source:
Returns:
Type
RequestBBox

clearCache()

clear all caches
Source:

get(ids, options, featureCallback, finalCallback) → {RequestGet}

Parameters:
Name Type Description
ids string | Array.<string> Id or array of Ids of OSM map features, e.g. [ 'n123', 'w2345', 'n123' ]. Illegal IDs will not produce an error but generate a 'null' object.
options object Various options, see below
Properties
Name Type Attributes Default Description
priority number <optional>
 0 Priority for loading these objects. The lower the sooner they will be requested.
sort string | boolean <optional>
 false When set to true or "index", the function featureCallback will be called in order of the "ids" array. When set to false or null, the featureCallback will be called as soon as the object is loaded (e.g. immediately, if it is cached). When set to "BBoxDiagonalLength", the objects are ordered by the length of the diagonal of the bounding box.
sortDir "asc" | "desc" <optional>
 "asc" Sort direction.
bounds BoundingBox | GeoJSON <optional>
 Only return items which intersect these bounds. Boundaries is a BoundingBox, or a Leaflet Bounds object (e.g. from map.getBounds()) or a GeoJSON Polygon/Multipolygon.
members boolean <optional>
 false Query relation members of. Default: false
memberCallback function <optional>
 For every member, call this callback function. (Requires options.members=true)
memberProperties bit_array <optional>
 Which properties should be loaded for the members. Default: OverpassFrontend.TAGS | OverpassFrontend.MEMBERS | OverpassFrontend.BBOX
memberBounds BoundingBox | GeoJSON <optional>
 Only return members which intersect these bounds. Boundaries is a BoundingBox, or a Leaflet Bounds object (e.g. from map.getBounds()) or a GeoJSON Polygon/Multipolygon.
featureCallback function Will be called for each object which is passed in parameter 'ids'. Will be passed: 1. err (if an error occured, otherwise null), 2. the object or null, 3. index of the item in parameter ids.
finalCallback function Will be called after the last feature. Will be passed: 1. err (if an error occured, otherwise null).
Source:
Returns:
Type
RequestGet

getCached(id, options) → {null|false|OverpassObject}

return an OSM object, if it is already in the cache
Parameters:
Name Type Description
id string Id of an OSM map feature
options object
Properties
Name Type Attributes Description
properties int <optional>
 Which properties have to be known (default: OverpassFrontend.DEFAULT)
Source:
Returns:
- null: does not exist in the database; false: may exist, but has not been loaded yet (or not enough properties known); OverpassObject: sucessful object
Type
null | false | OverpassObject

getMeta()

get meta data of last request or - if no request was submitted - the first.
Source:

Type Definitions

Context

Current request context
Type:
  • Object
Properties:
Name Type Description
query string The compiled code of all sub requests
queryOptions string The compiled queryOptions which will be sent to Overpass API
requests Array.<Request> List of all requests in the context
subRequests Array.<Request#SubRequest> List of all subRequests in the context
bbox BoundingBox when there are any BBox requests, add this global bbox
maxEffort int how many queries can we still add to this context
todo object list of items which should be loaded via get requests to avoid duplicates
Source:

QueryStatus

Status of a query to Overpass API
Type:
  • Object
Properties:
Name Type Attributes Description
status int <optional>
 result status (e.g. 429 for reject, ...)
errorCount int <optional>
 the nth error in a row
retry boolean <optional>
 true, if the request will be retried (after a 429 error)
retryTimeout int <optional>
 if the query will be retried, the next request will be delayed for n ms
Source:

Events

error

An error occured
Parameters:
Name Type Attributes Description
error Error
context OverpassFrontend#Context <optional>
 context of the request
Source:

load

When a file is specified as URL, this event notifies, that the file has been completely loaded. When a Overpass API is used, every time when data has been received.
Parameters:
Name Type Attributes Description
osm3sMeta object Meta data (not all properties of meta data might be set)
Properties
Name Type Attributes Description
version number OpenStreetMap API version (currently 0.6)
generator string Data generator
timestamp_osm_base string RFC8601 timestamp of OpenStreetMap data
copyright string Copyright statement
bounds BoundingBox <optional>
 Bounding Box (only when loading from file)
context OverpassFrontend#Context <optional>
 context of the request
Source:

reject

A request to Overpass API was rejected
Parameters:
Name Type Description
queryStatus OverpassFrontend#QueryStatus
context OverpassFrontend#Context context of the request
Source:

start

A request to Overpass API is started
Parameters:
Name Type Description
reserved object
context OverpassFrontend#Context context of the request
Source:

update

When an object is updated (e.g. when loaded; additional information loaded; when a member object got loaded)
Parameters:
Name Type Description
object OverpassNode | OverpassWay | OverpassRelation The object which got updated.
Source: