wiki:Maps

Version 592 (modified by aharvey, 9 months ago) ( diff )

<category> is mandatory, without it the Imagery Source entry won't be picked up by JOSM

Imagery sources

Table of Contents

  1. Documentation
    1. General properties
    2. Tile Map Services (TMS)
    3. Web Map Services (WMS)
    4. Web Map Tile Services (WMTS)
    5. Mapbox Vector Tile Services (MVT)
    6. Other important information
  2. List of sources

This wiki page provides imagery sources for JOSM. You can add more WMS, TMS and WMTS sources to the list below by editing the corresponding county specific subpage (or the subpage for worldwide sources), but source:trunk/resources/images/misc/error.svg always make sure the OpenStreetMap community is allowed to use them source:trunk/resources/images/misc/error.svg. Please get in contact with the OSM community if you are unsure about the license/permission. Please read the following documentation before adding or editing sources.

Documentation

General properties

General properties of <entry>: (<name>, <id>, <category>, <type> and <url> are mandatory.)

Some notes: the historic variant of photo and map should be used either if the source shows very old data or if there is a newer variant of the same source from the same provider available. E.g. for the entries london_orthophoto_2018, london_orthophoto_2019 and london_orthophoto_2020 use photo for the 2020 variant and historicphoto for the other two. If a source is specialized on one or two features e.g. shows only landuses or only roads and rivers or only buildings use other rather than map.
Property Description
name The name of the imagery source. Use English here only. These names can then be translated into all supported languages via ​Launchpad. (Optional attribute: lang containing the language code to give a translated name here in the xml file. However this should be avoided. This also overrides the translation from Launchpad.)
id Unique identifier of a map to allow automatic updates of map data in JOSM. Don't use white spaces and special characters here (except - and _). Never change an existing id as this would break the idea behind the id.
oldid In case renaming is necessary this can contain an old id. The attribute date containing an ISO data like 2018-08-14 is required. Multiple entries are possible.
category Type of imagery: photo aerial or satellite photo, map a map, historicmap historic or otherwise outdated map, osmbasedmap map based on OSM data, historicphoto historic or otherwise outdated aerial or satellite photo, elevation a map of digital terrain model, digital surface model or contour lines, qa map for quality assurance, other any other type or WMTS/wms_endpoint sources containing layers of different categories.
description Description of the imagery source, when not self explaining - i.e. when not aerial imagery or other relevant specific information, required attribute: lang containing the language code. The first description must be in English with the language code en for translation in Launchpad. The description is displayed in JOSM in the mouse over tool tip in the imagery preferences, the Imagery menu and in the toolbar.
type The type. Can be tms, wmts, wms, wms_endpoint and mvt. If wms_endpoint is used then the user can choose one of the provided wms layers when adding the entry as background. In addition, there are the special types bing and scanex with hardcoded behaviour.
url The URL of the service. Can contain templates, e.g. {zoom} will be replaced by the current zoom level (see below). The list of services is a XML document, so if the URL contains a & character, the URL must be wrapped in <![CDATA[...]]>. (Technically alternatively the & character could be replaced by &amp; but that makes comparing urls harder and is therefore strongly discouraged.)
custom-http-headers HTTP headers to be sent to server (replacement of {header(header, value)}). It has two attributes header-name and header-value. Might be specified multiple times.
default If set to "true", the entry is in the users list by default. (Only josm wiki administrators can change default entries.)
date Creation date of imagery in form YYYY-MM-DD;YYYY-MM-DD. DD and MM as well as a second date are optional. a single "-" marks an unknown or open timespan. Examples 2015 or 2015;2016 or 2015-10;2016-01 or 2015;-. The date is displayed in JOSM in the mouse over tool tip in the imagery preferences, the Imagery menu and in the toolbar.
bounds The area of use, e.g. <bounds min-lat='45.7' min-lon='5.9' max-lat='55.0' max-lon='17.3'/>
shape A non-rectangular area of use inside the <bounds>, defined by an ordered list of <point>s. This allows a more precise display in Imagery preferences. To easily create the shape xml code you can use the ​Imagery-XML-Bounds plugin.
point A lat/lon point, part of its parent <shape>, e.g <point lat='45.4023663' lon='2.4599585' />
permission-ref Provide a source that this background can be used for OSM. A page on the OSM-wiki with additional explanation and further references is preferred, but other sources (for example the license text) can also be linked. The document does not have to be in English. Please always use this property when adding new entries so it is easier for others to review.
eula A link to an EULA text that has to be accepted by the user, before the imagery source is added. Can contain {lang} to be replaced by a current user language wiki code (like FR:) or an empty string for the default English text.
attribution-url A link that is opened, when the user clicks on the attribution text. If attribution-url is set also attribution-text must be set, else no attribution will be displayed.
attribution-text The attribution text to be shown all the time in the mapview.
logo-url A link that is opened, when the user clicks on the attribution image
logo-image A URL for an image, that is displayed in the mapview for attribution
terms-of-use-url A link that is opened, when the user clicks on the terms-of-use text
terms-of-use-text Customized text for the terms of use link (default is "Background Terms of Use")
country-code The ​ISO 3166-1 alpha-2 country code
icon A menu/toolbar icon specified either as URL or data URL (RFC2397)
mirror A different mirror of the data, e.g. a TMS for WMS servers. Supports <type>, <id>, <url>, <projections>, <min-zoom>, <max-zoom> and <privacy-policy-url> properties.
no-tile-header Specifies a header returned by tile server, when no tiles are available at this zoom level. name attribute contains name of the header, and value attribute contains regex, that should match header value.
no-tile-checksum Specify a checksum for tiles, which aren't real tiles. type is the digest type and can be MD5, SHA-1, SHA-256, SHA-384 and SHA-512, value is the hex encoded checksum in lower case. To create a checksum save the tile as file and upload it to e.g. ​https://defuse.ca/checksums.htm.
metadata-header header-name attribute specifies a header returned by tile server, that will be shown as metadata-key attribute in Show Tile Info dialog
valid-georeference Set to true if imagery source is properly aligned and does not need imagery offset adjustments. This is used for OSM based sources too.
minimum-tile-expire minimum expiry time for tiles in seconds. The larger the value, the longer entry in cache will be considered valid Since r13733.
privacy-policy-url A link to the privacy policy of the operator. Since r16127 This property is not used within JOSM but other services may use it.
Attribute Description
eli-best Set to "true", when marked as best in ​​GitHub project Editor Layer Index. A hint is then displayed in JOSM in the mouse over tool tip in the imagery preferences, the Imagery menu and in the toolbar.
overlay This entry is an overlay (i.e. mainly transparent)

Attributes are included directly within the <entry> property, e.g. <entry eli-best="true">`.

When {header(header,value)} is included in the URL, this part is stripped and send as HTTP header to the server. (Deprecated, use custom-http-headers instead.)

Tile Map Services (TMS)

Properties specific to Tile Map Service:

Property Description
tile-size Size of individual tiles delivered by this service, defaults to 256.
min-zoom The minimum zoom level
max-zoom The maximum zoom level. For higher scales, the images of the maximum level are enlarged. Default value is 20.
mod-tile-features Whether tiles status can be accessed by appending /status to the tile URL and can be submitted for re-rendering by appending /dirty. Since r13272.

For TMS you can specify tile URL template. Following patterns are supported:

  • {zoom} is replaced by tile zoom level, also supported:
    • offsets to the zoom level: {zoom+1} or {zoom-1}
    • reversed zoom level: {19-zoom}
    • Since revision 6951 also {z} and variants are supported for compatibility with other applications (however you should use {zoom} in this wiki)
  • {x} is replaced by X-coordinate of the tile
  • {y} is replaced by Y-coordinate of the tile
  • {!y} is replaced by 2zoom-1 - 1 - Y (Yahoo style Y coordinate)
  • {-y} is replaced by 2zoom - 1 - Y (OSGeo Tile Map Service Specification style Y coordinate)
  • {switch:...} is replaced by a random selection from the given comma separated list, e.g. {switch:a,b,c} or {switch:1,2,3,4}. This allows several simultaneous HTTP connections by splitting the download to several subdomains which makes the tile download faster.
  • {apikey} is replaced by the JOSM custom API Key for the given id, if defined on the JOSM web server

Web Map Services (WMS)

Properties specific to Web Map Service:

Property Description
tile-size Size of individual tiles requested, defaults to the "tile size" preference from Help/Preferences/Imagery#Settings (512).
min-zoom The minimum zoom level
max-zoom The maximum zoom level. For higher scales, the images of the maximum level are enlarged. Default value is 20.
projections A list of supported projections (inside <code> tags)
code A projection name, part of its parent <projections>, e.g <code>EPSG:4326</code>
default-layers default layer to open (when using WMS_ENDPOINT type). Contains list of layer tag with two attributes - name and style, (not allowed in <mirror> tag). E.g.:
<default-layers>
<layer name="Basisdata_NP_Basiskart_JanMayen_WMTS_25829" style="default" />
</default-layers>
format format to use when connecting tile server (when using WMS_ENDPOINT type)
transparent accepts two values - true and false. If true transparent tiles will be requested from server

Projections can be tested within the JOSM wiki by adding &epsg=... to the view URL. Small numbers refer to the projection specified in the wiki entry and large numbers directly to the EPSG code. So &epsg=3 means the 3rd projection in the wiki entry list and &epsg=4326 means EPSG:4326. With the second variant you can also test projections which are not (yet) part of the wiki entry list.

For WMS you can specify tile URL template. Following patterns are supported:

  • {proj} is replaced by projection.
  • {bbox} is replaced by bounding box using projected coordinates
  • {width} is requested display width
  • {height} is requested display height
  • {time} asks user to input a time filter such as 2020-01-10T00:00:00Z/2020-01-20T00:00:00Z
  • {w},{s},{n},{e} are replaced by corresponding coordinates
  • {wkid} is replaced by projection "well known id", i.e. {proj} with "EPSG:" string stripped of
  • {apikey} is replaced by the JOSM custom API Key for the given id, if defined on the JOSM web server

To find out all the needed parameters of a WMS open the GetCapabilities URL. It usually looks like this http://...service=wms&request=getcapabilities

The wiki can help you to find projection codes. When adding or changing a WMS entry you may add EXTRACTEPSG as only content of the line after the WMS URL. Then preview the changes. You will get a XML validation error, but the preview contains the standard projections supported by the server.

Web Map Tile Services (WMTS)

Properties specific to Web Map Tile Service:

Property Description
projections A list of supported projections (inside <code> tags)
code A projection name, part of its parent <projections>, e.g <code>EPSG:4326</code> (see also projection hints in the WMS section above)
default-layers default layer to open (when using WMS_ENDPOINT type). Contains list of layer tag with three attributes - name, style and tile-matrix-set, (not allowed in <mirror> tag). E.g.:
<default-layers>
<layer name="Basisdata_NP_Basiskart_JanMayen_WMTS_25829" style="default" tile-matrix-set="default028mm" />
</default-layers>

For WMTS you specify the URL to the GetCapabilities document. JOSM will fetch the document and interpret all the data there. If there is more than one layer within one service, JOSM will ask the user, which tile he wants to work with. Multiple styles are not yet supported.

For WMTS you can specify tile URL template. Following patterns are supported:

  • {apikey} is replaced by the JOSM custom API Key for the given id, if defined on the JOSM web server

Mapbox Vector Tile Services (MVT)

Properties specific to Mapbox Vector Tile Services:

Property Description
min-zoom The minimum zoom level
max-zoom The maximum zoom level. For higher scales, the images of the maximum level are enlarged. Default value is 20.

MVT services use the same template information as seen in #TileMapServicesTMS.

For MVT services, you may specific a url to a ​Mapbox Vector Style sheet. If a vector tile style sheet is specified, max-zoom and min-zoom properties do not need to be specified, as the vector tile style sheet should include that information for all the sources and layers in the vector tile style sheet.

At this time (2021-08-04) it is preferred that non-shared style sheets be stored in JOSM plugin SVN.

Other important information

  • Please use the preferred order of properties for better readability: name, id, oldid (if present), category, then everything else, and at the end icon, bounds. (The last two are usually the longest.)
  • JOSM uses this URL to fetch the imagery sources. The URL can be customized in the advanced preferences (key imagery.layers.sites). Using multiple sources at the same time is possible.
  • Normally JOSM ignores any elements that it does not recognize. However, it will skip the entire imagery entry, when one of the unsupported tags has the attribute mandatory='true'. This is only relevant, when essential new features are added, but old versions of JOSM are still in use.
  • The OSM editors iD, Potlatch 2 and Vespucci use the imagery list provided by the GitHub project ​Editor Layer Index. Differences between this list and the JOSM list are detected by ImageryCompare and synced manually. This page includes some sanity checks too. After you made changes or additions to imagery sources check this page for red marked errors/conflicts which must be resolved!
  • Additional to the XML database there is also an geojson output which can be found here: pretty and default, and a Potlatch-format output which can be found here: pretty and default.
  • License: Like the whole wiki (see page footer) the imagery database is licensed under Creative Commons (CC-BY-SA). Content since April 2014 is dual licensed with LGPL (except contents copied from ELI, which is only CC-BY-SA).

List of sources

Note: See TracWiki for help on using the wiki.