Import/Guidelines
The Import Guidelines, along with the Automated Edits code of conduct, shall be followed when importing data from external sources into the OpenStreetMap database. Imports are planned and executed with more care and sensitivity than other edits, because poor imports have significant impacts on both existing data and local mapping communities. The Data Working Group is tasked by the OSMF to detect and stop imports that do not comply with these guidelines. Not following these guidelines puts your account at risk of being blocked.
Process
If your city/county/state/country government, a non-profit, or some other organization or person has great data that could be used to improve the quality of OpenStreetMap, here's what you need to know, starting with an overview of the process. These areas are expanded in further sections of this page, and on related pages.
Step 1: Prerequisites
- Gain familiarity with the basics of OpenStreetMap, including editing.
- Review what can go wrong with imports.
- Identify data you'd like to import. (ex: buildings, landuse, POIs, addresses, etc.)
- Be aware of OpenStreetMap licensing
- Review the import guidelines fully before beginning.
- Contact the community to gauge interest in importing the data.
Step 2: License approval
- You must obtain proper permissions and licenses to use the data in OSM from the data owner. If the license of the data is not compatible with the OpenStreetMap ODbL, you can not use the data. Data may not have a clear license, a restrictive license, an open license that isn't compatible with OSM, or may only include a disclaimer. In these cases, you must contact the data manager or agency to ask for clarification or permission to use the data. Sometimes, getting permission to use data, even if the existing license might seem prohibitive, is as simple as asking the appropriate authority if they are willing to comply with the terms of the OpenStreetMap Open Database License. See Import/Getting Permission for example emails that touch on important issues. See also ODbL Compatibility for a quick view of some compatible and incompatible licenses of data to import.
Step 3: Documentation
- You must write a plan for your import in the OSM wiki. Create a wiki page outlining the details of your plan. This plan must include information such as plans for how to convert the data to OSM XML, dividing up the work, how to handle conflation, how to map GIS attributes to OSM tags, how to potentially simplify any data, how you plan to divide up the work, revert plans, changeset size policies, and plans for quality assurance. Use Import/Plan Outline as the backbone to your documentation page.
Step 4: Community Buy-in
- Discuss your plan. Contact the local OSM community to notify them of your plans, including a link to your wiki page. This will help gain the benefit of past experiences, which may include having already reviewed the data you're considering for import. Check for local user groups, local chapters, and country-specific mailing lists. The osm-community-index can be used to locate some active local communities.
- Be prepared to answer questions from the community. Discuss with the community the suitability of each layer for importing. Some data can be readily imported without much difficulty, while others are far more difficult (e.g. street centerlines).
- You must not import the data without local buy-in.
Step 5: Import Review
- Once the data has been completely prepared and documented, you may submit your review post.
- You must submit a new post to the Community Forum, to the relevant local community, or to the general channel if no category for the community exists. The post must have the
importandimport-proposaltags, and follow this template. - After 14 days have passed, and all concerns have been addressed, the import may begin.
Step 6: Uploading
- Use your <username>_Import account.
- Follow your plan.
- Track your progress.
- Provide updates to the community on your efforts.
- Let everyone know when you're done.
Key considerations
Discuss your proposed import
Discuss your import with appropriate local communities and on the imports@openstreetmap.org mailing list. Reach out to your local community through the appropriate communication channels. Many local communities have their own wiki pages.
Even if the same or similar import has been discussed before, you should still discuss it with the local community. This means that they are aware of your plans and can raise any issues or clashes before any damage occurs. This is especially true if the data has been available for a long time and has not yet been imported – this does not mean it is acceptable to proceed without discussion with the local community.
Imports related to humanitarian issues, disaster response, or development should consult the HOT (ideally on the HOT Mailing list) as an additional measure.
Document your import
- Main article: Import/Plan Outline
If you are going ahead with your import, please create a page about it on the wiki, with all the details. Also link to your page from any local pages about your city or country. The page should have the following details:
- Data source accuracy and licensing
- Import/Software you plan to use. Share the source code you are using.
- Exactly how data will be translated from another format into OSM format
- How the resulting data will look. Exact tags being used.
- Username of the account performing the import, and other details of how the changesets will be tagged
And as the import progresses
- Link to example data imported on the live database.
Note that changing the scope of the import after the consultation will invalidate the consultation. You cannot have people agree to an import of a data set X and then import X+Y.
Ensure that the data license is OK
We are only interested in 'free' data. We must be able to release the data with our OpenStreetMap License. We are allowed to use public domain data sources, of which there are quite a few, but beyond that, it gets more complicated.
Your data must be compatible with the ODbL.
You must not claim an additional copyright for yourself as the importer. For example, if you import public domain data, you must not seek to restrict the use of your imported data. Your import account must not refuse any permissions that were given by the original creators of the data you're importing.
Please also note the details of attribution requirement. We can offer some attribution:
- The source can be mentioned on the Contributors page of the wiki
- Very large scale contributions can be listed on openstreetmap.org/copyright
- Information about the source will be listed on the import account and changesets, and can be referenced easily in object history
If none of these are acceptable attribution for a data source, you cannot proceed with the import.
Data that purports to be available under a compatible license may ultimately be derived from sources that we consider to be non-free. For example, although some geodata is available from Wikipedia under a Creative Commons license it is a widely held belief in OSM that some of the data is simply derived from Google Maps, and therefore not actually available under the stated license. In such cases, do not import data of uncertain origin, regardless of the stated license.
Import review
Use this template to submit your review to the community forum. Include the tags import and import-proposal. Set the subject as Proposed import of (Database).
If you are submitting your post via email, set the subject: [import import-proposal] Proposed import of (Database).
# Import Title
Hello (COMMUNITY), I am proposing to import the (DATASET) dataset, sourced from (AGENCY).
## Documentation
This is the wiki page for my import:
wiki.openstreetmap.org/wiki/
This is the source dataset's website:
http://example.org/
The data download is available here:
http://example.org/download
This is a file I have prepared which shows the data after it was translated to OSM schema:
https://drive.google.com/file/
(Replace the links with the links for your Import)
## License
I have checked that this data is compatible with the ODbL.
This data is distributed under (LICENSE).
(If you have received special permission/waiver, mention it here.)
## Abstract
(Provide a summary of your import. Be sure to mention:
* Information about the dataset
* Your relationship to the dataset, if any.
* What the dataset contains.
* The size of the dataset.
* The method you are using to import into OSM.
* How you plan to translate the dataset tags to OSM schema, including the table of tags used on imported objects.
* Your approach to conflation.
* Any scripts you are using.)
Using a Dedicated User Account for Imports
When conducting large imports in OpenStreetMap, it's recommended to use a specialized account. Follow these guidelines to set up your import account effectively:
1. Account Naming: Name your account in this format: (YourUsername)_Import. For example, "MapMaster_Import" for a user named MapMaster.
2. Link to Main Account: Include a link to your primary OSM account in your import account's profile to establish a clear connection between your accounts.
3. Link to Import Wiki Page: Add a link in your import account's profile to the wiki page detailing your import. This is essential as changeset histories in OSM are permanent.
4. Importer Role: OpenStreetMap includes a feature that limits uploads to prevent vandalism. Your import may hit this limit. If it does, please email the Data Working Group at data@openstreetmap.org with details about your import, such as the wiki site. The DWG can assign the importer role to avoid the limit. The role is not required to do imports.
5. Email Address for Multiple Accounts: Your import account cannot have the same email address associated as your regular account has. You will need to set up a separate email address and forward emails or use a sub-address if your email provider supports it.
Adhering to these guidelines will help organize your import activities and maintain transparency within the OSM community.
Use the right tags
Your import shall use tags which are familiar to the OSM community, rather than inventing tags.
You may have some metadata like the IDs used for your original data. Do not document database values that don't have any ties to reality. Your data source may have many many fields, only include real and Verifiable metadata.
Don't put data on top of data
Unlike traditional GIS systems, OpenStreetMap has no concept of layers. Conflation is required to ensure that duplicate data is not added to OSM. Use tools such as the JOSM conflation plugin and the geometry tools in QGIS to eliminate duplicate data from your import. Discuss with the community and document your approach to conflation.
Take great care to avoid damaging the database
Take great care to avoid damaging the database and don't leave a messy import for others to clean up.
If your import does 'go wrong', or you needed to interrupt an upload half-way through, then this should be reverted promptly. If you need help, then contact Imports or other community members. If you don't know how to revert an import, don't conduct the import in the first place. Address any concerns and complaints from other users about your import as soon as possible.