Context Navigation

Editing Maps

Adjust edit area height: Edit side-by-side

= Imagery sources =

[[PageOutline(2-4,Table of Contents)]]

This wiki page provides imagery sources for JOSM. You can add more WMS, TMS and WMTS sources to the list [#Listofsources below] by editing the corresponding county specific subpage (or the subpage for worldwide sources), but [[JOSMImage(misc/error,20,middle)]] '''always make sure the OpenStreetMap community is allowed to use them''' [[JOSMImage(misc/error,20,middle)]]. 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 == #Documentation
=== General properties ===

General properties of {{{<entry>}}}: ({{{<name>}}}, {{{<id>}}}, {{{<category>}}}, {{{<type>}}} and {{{<url>}}} are mandatory.)
||= '''Property''' =||= '''Description''' =||
|| '''name''' || The name of the imagery source. Use English here only. These names can then be translated into all supported languages via [https://translations.launchpad.net/josm/trunk/+pots/josm 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.[[BR]]
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}}}. ||
|| '''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 [wikitr:/Help/Menu/Imagery 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 [wikitr:/Help/Preferences/Imagery Imagery preferences]. To easily create the shape xml code you can use the [osmwiki:JOSM/Plugins/Imagery-XML-Bounds 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 [wikitr:/Help/MapView 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 [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 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 [https://github.com/osmlab/editor-imagery-index 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 2^zoom-1^ - 1 - Y (Yahoo style Y coordinate)
 * {-y} is replaced by 2^zoom^ - 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 [https://docs.mapbox.com/mapbox-gl-js/style-spec/ 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 [/maps 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 [https://github.com/osmlab/editor-layer-index 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: [/maps?format=geojson&pretty=true pretty] and [/maps?format=geojson default], and a Potlatch-format output which can be found here: [/maps?format=potlatch&pretty=true pretty] and [/maps?format=potlatch 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 == #Listofsources

[[MapsIndex]]

Note: See WikiFormatting and TracWiki for help on editing wiki content.

Change information

Your email or username:

E-mail address and name can be saved in the Preferences

Comment about this change (optional):

Note: See TracWiki for help on using the wiki.