9 | | Geo data edited in JOSM is only available locally and only usable by the user who entered the data unless the user decides to make it available to the community too. In order to publish data the user has to **upload** it. Uploading means that the geo data is transferred to a central server run by the OSM community where it is integrated with geo data from other mappers in a central database. It's by uploading data that locally edited geo data both becomes part of the [http://www.openstreetmap.org public maps] and can be used by other members of the OSM community. |
10 | | |
11 | | {{{ |
12 | | #!html |
13 | | <p style="background-color:rgb(253,255,221);padding: 10pt; border-color:rgb(128,128,128);border-style: solid; border-width: 1px;"> |
14 | | Please be careful with editing and uploading data. When in doubt that everything is okay, refrain from uploading and save the area locally to disk, check what you need and try again later. |
15 | | </p> |
16 | | }}} |
17 | | |
18 | | [[TOC(inline)]] |
| 10 | Geo data edited in JOSM is only available locally and only usable by the user who entered the data unless the user decides to make it available to the community too. In order to publish data the user has to **upload** it. Uploading means that the geo data is transferred to a central server run by the OSM community where it is integrated with geo data from other mappers in a central database. It's by uploading data that locally edited geo data both becomes part of the main database and [osmwww: map at osm.org] and can be used by other members of the OSM community. |
| 11 | |
| 12 | |
| 13 | == In simple words == |
| 14 | * (like online editors like iD or Potlatch) you need to upload your changes to OSM server. Make sure you connected to server :-) |
| 15 | * you may encounter [wikitr:/Help/Concepts/Conflict conflicts] after you upload changes (in most cases this means you will have to [wikitr:/Help/Dialog/Conflict#Resolvingdifferencesbetweentags choose what tags to leave on your objects]) |
| 16 | * to reduce chance of conflict: |
| 17 | * don't edit data other mappers edit in same time window |
| 18 | * make your downloads-uploads quicker, so there no overlap between your time-window and theirs |
| 19 | * (rough idea) to entirely avoid conflict, don't edit objects with same id and don't alter their parent relations (node-way and way-relation and relation-relation). If you (and other editor) are editing disjoint datasets (https://en.wikipedia.org/wiki/Disjoint_sets), then there won't be conflict at all. Please note that it also means that all parent ways and all parent relations should be respected (which is likely to change). |
| 20 | * (unlike online editors like iD or Potlatch) you don't have to upload immediately (you may [wikitr:/Help/Action/Save save] file manually but [wikitr:/Help/Action/AutoSave auto save] will further assist you) |
| 21 | * (unlike every other editor?) JOSM will let you upload changes to already opened (but not a closed) changeset (see [#Multipleuploadsintoonechangeset Multiple uploads into one changeset]). Every open changeset will "close" automatically by [osmwww: OSM server] after 1 hour. |
21 | | Geo data contributed to the OSM server consists of [Concepts/Object nodes, ways, and relations]. Because there are hundreds of mappers publishing their geo data on the OSM server it is important to track who published what data in which context. It would be tedious for mappers to describe why every single node and every single way is published. A more convenient approach is to package a group of related objects and assign the package itself a comment, instead of the individual objects. |
22 | | |
23 | | The OSM project calls such a package a **[Concepts/Changeset changeset]**. A **changeset** is a collection of related changes (new objects, object modifications, or object deletions) applied to OSM data. |
24 | | |
25 | | Changesets are different from **upload requests**. A changeset is a **logical** grouping of [Concepts/Object objects], whereas an upload request is a **technical grouping** for transferring geo data to the central OSM server only. In JOSM we say, that objects are uploaded **using** upload requests **to** a changeset. The JOSM Upload Dialog allows aspects of the upload requests and changeset objects to be configured. Some of the settings are compulsory (i.e. the user has to configure them before geo data can be uploaded) but most of them are optional and JOSM works with reasonable default values. |
26 | | |
27 | | Geo data can be retrieved later via the changeset it was uploaded to, though it can't be retrieved by the upload request used. Changesets have a unique identifier, upload requests have not. For instance, [http://www.openstreetmap.org/browse/changeset/3274448 this changeset] includes geo data from tracing over orthofotos of the city of Bern, Switzerland. It isn't possible, though, to see the upload requests that were used to fill it. |
| 24 | Geo data contributed to the OSM server consists of [wikitr:/Help/Concepts/Object nodes, ways, and relations]. Because there are hundreds of mappers publishing their geo data on the OSM server it is important to track who published what data in which context. It would be tedious for mappers to describe why every single node and every single way is published. A more convenient approach is to package a group of related objects and assign the package itself a comment, instead of the individual objects. |
| 25 | |
| 26 | The OSM project calls such a package a **[wikitr:/Help/Concepts/Changeset changeset]**. A **changeset** is a collection of related changes (new objects, object modifications, or object deletions) applied to OSM data. |
| 27 | |
| 28 | Changesets are different from **upload requests**. A changeset is a **logical** grouping of [wikitr:/Help/Concepts/Object objects], whereas an upload request is a **technical grouping** for transferring geo data to the central OSM server only. In JOSM we say, that objects are uploaded **using** upload requests **to** a changeset. The JOSM Upload Dialog allows aspects of the upload requests and changeset objects to be configured. Some of the settings are compulsory (i.e. the user has to configure them before geo data can be uploaded) but most of them are optional and JOSM works with reasonable default values. |
| 29 | |
| 30 | Geo data can be retrieved later via the changeset it was uploaded to, though it can't be retrieved by the upload request used. Changesets have a unique identifier, upload requests have not. For instance, [osmwww:browse/changeset/3274448 this changeset] includes geo data from tracing over orthofotos of the city of Bern, Switzerland. It isn't possible, though, to see the upload requests that were used to fill it. |
35 | | * for users uploading the result of converting a few GPS traces to OSM geo data |
36 | | * for users uploading the result of tracing a few hours over aerial photos |
37 | | * for users uploading the result of entering local knowledge about street names, points of interests, etc. |
38 | | |
39 | | === Multiple uploads into one changeset === |
40 | | |
41 | | [[Image(one-changeset-multiple-upload-request.png)]] |
| 38 | * for users uploading the result of converting a few GPS traces to OSM geo data |
| 39 | * for users uploading the result of tracing a few hours over aerial photos |
| 40 | * for users uploading the result of entering local knowledge about street names, points of interests, etc. |
| 41 | |
| 42 | === Multiple uploads into one changeset ===#Multipleuploadsintoonechangeset |
| 43 | |
| 44 | [[Image(one-changeset-multiple-upload-request.png,link=)]] |
49 | | [[Image(one-changeset-individual-object-upload-request.png)]] |
50 | | |
51 | | Please note that this is a legacy feature. Until recently, this was the only upload option in OSM. Technically, it uses a slightly different approach to communicate with the OSM server. It is still available in JOSM although the OSM server now supports upload requests with up to 50,000 objects. For the casual and normal user it is almost obsolete. In rare cases, it could be useful for power users. |
| 52 | [[Image(one-changeset-individual-object-upload-request.png,link=)]] |
| 53 | |
| 54 | Please note that this is a legacy feature. Until recently, this was the only upload option in OSM. Technically, it uses a slightly different approach to communicate with the OSM server. It is still available in JOSM although the OSM server now supports upload requests with up to 10,000 objects. For the casual and normal user it is almost obsolete. In rare cases, it could be useful for power users. |
65 | | * **Time required to upload**: the smaller the upload requests you choose the longer it takes to upload. It takes more time to upload 100 objects using 100 individual upload requests than to upload them in one request containing 100 objects. |
66 | | |
67 | | * **Collisions with other mappers**: if you upload 30,000 objects in one request and if the server encounters a problem on the 29,999th object the whole upload is rolled back. The problem has to be fixed first (i.e. by resolving a [wiki:/Help/Concepts/Conflict conflict]). The whole 30,000 objects will then have to be uploaded again. On the other hand, if you upload 30,000 objects with 10 requests containing 1,000 objects each and the server encounters a problem on the 29,999th object then you only have to repeat the last upload request for the 29,000th to 30,000th objects. Objects 1-28,999 are already successfully uploaded. If you're mapping in areas where other mappers are active too you should therefore prefer smaller sizes for upload requests. |
68 | | |
69 | | == Uploading data == |
| 69 | * **Time required to upload**: the smaller the upload requests you choose the longer it takes to upload. It takes more time to upload 100 objects using 100 individual upload requests than to upload them in one request containing 100 objects. |
| 70 | |
| 71 | * **Collisions with other mappers**: if you upload 10,000 objects in one request and if the server encounters a problem on the 9,999th object the whole upload is rolled back. The problem has to be fixed first (i.e. by resolving a [wikitr:/Help/Concepts/Conflict conflict]). The whole 10,000 objects will then have to be uploaded again. On the other hand, if you upload 10,000 objects with 10 requests containing 1,000 objects each and the server encounters a problem on the 9,999th object then you only have to repeat the last upload request for the 9,001th to 10,000th objects. Objects 1-9,000 are already successfully uploaded. If you're mapping in areas where other mappers are active too you should therefore prefer smaller sizes for upload requests. |
| 72 | |
| 73 | |
| 74 | == Uploading data ==#UploadData |
88 | | === The Upload Dialog === |
89 | | |
90 | | [[Image(upload-dialog-screenshot.png)]] |
91 | | |
92 | | The upload dialog consists of two sections: |
93 | | * the upper half displays a summary of the objects to be added, to be modified, and to be deleted on the server |
94 | | * the lower part provides panels for configuring various aspects of the upload process |
95 | | |
96 | | When the Upload Dialog is launched it always displays the basic configuration panel which includes a text box for entering an upload comment and a summary of the other upload parameters for this upload. |
| 92 | === The Upload Dialog ===#UploadDialog |
| 93 | |
| 94 | [[Image(upload-dialog-screenshot.png,link=)]] |
| 95 | |
| 96 | since JOSM version 17708, the Upload Dialog is modified: |
| 97 | |
| 98 | The Upload Dialog consists of two sections: |
| 99 | * the left side displays a summary of the objects to be added, to be modified, and to be deleted on the server |
| 100 | * the right side provides tabs for configuring various aspects of the upload process |
| 101 | |
| 102 | When the Upload Dialog is launched it always displays the ''Description'' tab which allows you to enter the most important information about your [wikitr:/Help/Concepts/Changeset changeset]: |
| 103 | the changeset comment:: |
| 104 | It's important to provide a brief comment describing the changes you are uploading. This makes it easier for other contributors and for yourself to know what your changes are about and why you made the changes. |
| 105 | * if the comment is empty or too short: the text below the comment box warns you |
| 106 | [[Image(comment_empty.png,link=)]] |
| 107 | * if the comment is provided: the text below the comment thanks you |
| 108 | [[Image(comment_present.png,link=)]] |
| 109 | the changeset source:: |
| 110 | Specify the date source for the changes, to allow other contributors to check them if needed. |
| 111 | * if the data source is not specified: the text below the comment box warns you |
| 112 | [[Image(source_not_specified.png,link=)]] |
| 113 | * if the data source is provided: the text below the comment thanks you |
| 114 | [[Image(source_provided.png,link=)]] |
| 115 | |
| 116 | Below there is a summary of the other upload parameters for this upload. And a checkbox which sets the `review_requested=yes` changeset tag. |
100 | | 1. [#LaunchUploadDialog Launch] the Upload Dialog |
101 | | 2. Enter an upload comment. You **must** provide an upload comment of at least 3 characters. |
102 | | 3. Click on [[Image(source:trunk/images/upload.png,16)]] **Upload Changes** |
103 | | |
104 | | === Running an upload with advanced options === |
| 120 | See [wikitr:/Introduction#UploadingtoOSM "Uploading to OSM"]. |
| 121 | |
| 122 | === Running an upload with advanced options (Settings tab) ===#AdvancedOptions |
| 123 | |
| 124 | ==== Choosing the changeset to upload to ==== |
| 125 | In the Changeset Configuration Panel you can select what [wikitr:/Help/Concepts/Changeset changeset] the data is uploaded to, see the screenshot below: |
| 126 | |
| 127 | [[Image(changeset-config-panel-1_JOSMr18303.png,link=)]] |
| 128 | |
| 129 | To upload your data, you can choose from the drop down list ''(since r18283)'': |
| 130 | * JOSM uploads to a new changeset if [[JOSMImage(dialogs/changesetdialog,24,link=,bottom)]] **New changeset** is selected in the drop down list. This is the standard setting. |
| 131 | * If you want to upload to an existing changeset you have to select one of the available changesets from the drop down list (they are only available, in the list, if there are open changesets which you can upload data because you own them). Click on [[JOSMImage(dialogs/refresh)]] ''Refresh'' to load the list of available open changesets from the server. |
| 132 | |
| 133 | Click on [[JOSMImage(closechangeset,24,link=,bottom)]] **Close Changeset** to close the currently selected open changeset. This is for convenience only. You don't have to close a changeset here in order to run a successful upload. |
| 134 | |
| 135 | After a successful upload JOSM can either close the changeset used or leave it open for another upload. The default setting is to close it. You can configure whether JOSM should leave it open by unselecting the checkbox **Close changeset after upload**. |
| 136 | |
| 137 | ==== Configuring the number and size of upload requests ==== |
| 138 | JOSM uploads geo data with one or more **upload requests** to a [wikitr:/Help/Concepts/Changeset changeset] on the OSM server. In the Advanced Configuration Panel you can decide about the number and the size of upload requests, see screenshot: |
| 139 | |
| 140 | [[Image(advanced-config-panel.png,link=)]] |
| 141 | |
| 142 | Select **Upload data in one request** to upload all object in one request. If you're uploading a medium to large number of objects this might take some time and JOSM will not be able to inform you about the progress. There are only two outcomes of such an upload: the upload either succeeded or it didn't. In the former case everything is fine, in the later no objects at all have been uploaded. This kind of upload will never lead to a partial upload which is both its strength and its weakness. It can be its weakness if the entire upload fails because there is a problem in the very last object in the upload request. |
| 143 | |
| 144 | Select **Upload data in chunks of objects** to upload the objects in a sequence of requests with a predefined size. You can enter a preferred size for an upload request (called the "chunk size"). Depending on its value JOSM will submit a number of upload requests (the number is displayed on the right of the input field for the "chunk size"). In contrast to the former option, every upload of a chunk can either succeed or fail. You will get some coarse grained progress feedback because JOSM will inform you when an individual chunk has been uploaded successfully or when its upload has failed. Uploading in chunks is in most cases slower than uploading in one requests, though. |
| 145 | |
| 146 | Select **Upload each object individually** to upload each object with an individual upload request. You will get very fine grained progress feedback because JOSM will inform you when an individual object was uploaded successfully or when its upload has failed. Note that this option is in most cases the slowest option. |
| 147 | |
| 148 | **Recommendations** |
| 149 | * For small (<1,000 objects) to medium upload sizes (<5,000 objects), choose **Upload data in one request** |
| 150 | * For medium to large upload sizes (> 5,000 objects) choose **Upload data in chunks of objects**. A chunk size of 1,000 is a good value to start with. |
| 151 | * Don't use **Upload each object individually** unless you have a specific reason to do so. This is basically a legacy strategy from former versions of the OSM server. |
114 | | * Tags are your friends. Use them to describe the geo data you are uploading to the OSM server. |
115 | | * Use the tag {{{source}}} to describe the source of your geo data (examples: {{{traced from Yahoo Imagery}}}, {{{based on GPS traces and surveyed by bike}}}). |
116 | | * You don't have to add your user name to the tags. The link between the changeset and your OSM user account is maintained automatically. |
| 163 | * Tags are your friends. Use them to describe the geo data you are uploading to the OSM server. |
| 164 | * Use the tag {{{source}}} to describe the source of your geo data (examples: {{{traced from Yahoo Imagery}}}, {{{based on GPS traces and surveyed by bike}}}). |
| 165 | * You don't have to add your user name to the tags. The link between the changeset and your OSM user account is maintained automatically. |
120 | | ==== Choosing the changeset to upload to ==== |
121 | | In the Changeset Configuration Panel you can select what [wiki:/Help/Concepts/Changeset changeset] the data is uploaded to, see the screenshot below: |
122 | | |
123 | | [[Image(changeset-config-panel.png)]] |
124 | | |
125 | | JOSM uploads to a new changeset if **Upload to a new changeset** is selected. This is the standard setting. |
126 | | |
127 | | If you want to upload to an existing changeset you have to select one of the available changesets from the drop down list. This list is only enabled if there are open changesets which you can upload data to because you own them. Click on [[Image(source:trunk/images/dialogs/refresh.png)]] ''Refresh'' to load the list of available open changesets from the server. If there is at least one open changeset available you can select the radio button **Upload to an existing changeset** and select a changeset. |
128 | | |
129 | | Click on [[Image(source:trunk/images/closechangeset.png)]] **Close Changeset** to close the currently selected open changeset. This is for convenience only. You don't have to close a changeset here in order to run a successful upload. |
130 | | |
131 | | After a successful upload JOSM can either close the changeset used or leave it open for another upload. The default setting is to close it. You can configure whether JOSM should leave it open by unselecting the checkbox **Close changeset after upload**. |
132 | | |
133 | | |
134 | | ==== Configuring the number and size of upload requests ==== |
135 | | JOSM uploads geo data with one or more **upload requests** to a [Concepts/Changeset changeset] on the OSM server. In the Advanced Configuration Panel you can decide about the number and the size of upload requests, see screenshot: |
136 | | |
137 | | [[Image(advanced-config-panel.png)]] |
138 | | |
139 | | Select **Upload data in one request** to upload all object in one request. If you're uploading a medium to large number of objects this might take some time and JOSM will not be able to inform you about the progress. There are only two outcomes of such an upload: the upload either succeeded or it didn't. In the former case everything is fine, in the later no objects at all have been uploaded. This kind of upload will never lead to a partial upload which is both its strength and its weakness. It can be its weakness if the entire upload fails because there is a problem in the very last object in the upload request. |
140 | | |
141 | | Select **Upload data in chunks of objects** to upload the objects in a sequence of requests with a predefined size. You can enter a preferred size for an upload request (called the "chunk size"). Depending on its value JOSM will submit a number of upload requests (the number is displayed on the right of the input field for the "chunk size"). In contrast to the former option, every upload of a chunk can either succeed or fail. You will get some coarse grained progress feedback because JOSM will inform you when an individual chunk has been uploaded successfully or when its upload has failed. Uploading in chunks is in most cases slower than uploading in one requests, though. |
142 | | |
143 | | Select **Upload each object individually** to upload each object with an individual upload request. You will get very fine grained progress feedback because JOSM will inform you when an individual object was uploaded successfully or when its upload has failed. Note that this option is in most cases the slowest option. |
144 | | |
145 | | **Recommendations** |
146 | | * For small (<1,000 objects) to medium upload sizes (<5,000 objects), choose **Upload data in one request** |
147 | | * For medium to large upload sizes (> 5,000 objects) choose **Upload data in chunks of objects**. A chunk size of 1,000 is a good value to start with. |
148 | | * Don't use **Upload each object individually** unless you have a specific reason to do so. This is basically a legacy strategy from former versions of the OSM server. |
149 | | |
157 | | [[Image(large-upload-advanced-settings.png)]] |
158 | | |
159 | | For very large uploads, uploading in one request isn't possible and the respective option is therefore disabled. Please select a chunk size to be used in the upload. It has to be smaller than 50,000, too, because the upper limit for the size of a changeset also applies to the chunk size. You can upload a very large dataset with an individual request per object but you're not recommended to do so. |
160 | | |
161 | | A very large upload doesn't fit within a single changeset. Please select |
162 | | |
163 | | * whether JOSM should automatically open as many new changesets as required to upload the data. Select this option if you want to run a very large upload without user intervention. |
164 | | |
165 | | * whether JOSM should fill up one changeset and return to the Upload Dialog. Select this option if you want to have full control over the changesets created for the upload. |
| 176 | [[Image(large-upload-advanced-settings.png,link=)]] |
| 177 | |
| 178 | For very large uploads, uploading in one request isn't possible and the respective option is therefore disabled. Please select a chunk size to be used in the upload. It has to be smaller than 10,000, too, because the upper limit for the size of a changeset also applies to the chunk size. You can upload a very large dataset with an individual request per object but you're not recommended to do so. |
| 179 | |
| 180 | A very large upload doesn't fit within a single changeset. Please select: |
| 181 | |
| 182 | * whether JOSM should automatically open as many new changesets as required to upload the data. Select this option if you want to run a very large upload without user intervention. |
| 183 | |
| 184 | * whether JOSM should fill up one changeset and return to the Upload Dialog. Select this option if you want to have full control over the changesets created for the upload. |
| 185 | |