osmapi
======
[](https://github.com/metaodi/osmapi/actions/workflows/build.yml)
[](https://pypi.python.org/pypi/osmapi/)
[](https://github.com/metaodi/osmapi/blob/master/LICENSE.txt)
[](https://coveralls.io/r/metaodi/osmapi?branch=develop)
[](https://github.com/psf/black)
[](https://github.com/pre-commit/pre-commit)
Python wrapper for the OSM API (requires Python >= 3.8)
## Installation
Install [`osmapi` from PyPi](https://pypi.python.org/pypi/osmapi) by using pip:
pip install osmapi
## Documentation
The documentation is generated using `pdoc` and can be [viewed online](http://osmapi.metaodi.ch).
The build the documentation locally, you can use
make docs
This project uses GitHub Pages to publish its documentation.
To update the online documentation, you need to re-generate the documentation with the above command and update the `master` branch of this repository.
## Examples
To test this library, please create an account on the [development server of OpenStreetMap (https://api06.dev.openstreetmap.org)](https://api06.dev.openstreetmap.org).
Check the [examples directory](https://github.com/metaodi/osmapi/tree/develop/examples) to find more example code.
### Read from OpenStreetMap
```python
>>> import osmapi
>>> api = osmapi.OsmApi()
>>> print(api.NodeGet(123))
{u'changeset': 532907, u'uid': 14298,
u'timestamp': u'2007-09-29T09:19:17Z',
u'lon': 10.790009299999999, u'visible': True,
u'version': 1, u'user': u'Mede',
u'lat': 59.9503044, u'tag': {}, u'id': 123}
```
### Constructor
```python
import osmapi
api = osmapi.OsmApi(api="https://api06.dev.openstreetmap.org", username = "you", password = "***")
api = osmapi.OsmApi(username = "you", passwordfile = "/etc/mypasswords")
api = osmapi.OsmApi(passwordfile = "/etc/mypasswords") # if only the passwordfile is specified, the credentials on the first line of the file will be used
```
Note: Each line in the password file should have the format _user:password_
### Write to OpenStreetMap
```python
>>> import osmapi
>>> api = osmapi.OsmApi(api="https://api06.dev.openstreetmap.org", username = u"metaodi", password = u"*******")
>>> api.ChangesetCreate({u"comment": u"My first test"})
>>> print(api.NodeCreate({u"lon":1, u"lat":1, u"tag": {}}))
{u'changeset': 532907, u'lon': 1, u'version': 1, u'lat': 1, u'tag': {}, u'id': 164684}
>>> api.ChangesetClose()
```
### OAuth authentication
Username/Password authentication will be deprecated in July 2024
(see [official OWG announcemnt](https://blog.openstreetmap.org/2024/04/17/oauth-1-0a-and-http-basic-auth-shutdown-on-openstreetmap-org/) for details).
In order to use this library in the future, you'll need to use OAuth 2.0.
To use OAuth 2.0, you must register an application with an OpenStreetMap account, either on the
[development server](https://master.apis.dev.openstreetmap.org/oauth2/applications)
or on the [production server](https://www.openstreetmap.org/oauth2/applications).
Once this registration is done, you'll get a `client_id` and a `client_secret` that you can use to authenticate users.
Example code using [`cli-oauth2`](https://github.com/Zverik/cli-oauth2) on the development server, replace `OpenStreetMapDevAuth` with `OpenStreetMapAuth` to use the production server:
```python
import osmapi
from oauthcli import OpenStreetMapDevAuth
client_id = "<client_id>"
client_secret = "<client_secret>"
auth = OpenStreetMapDevAuth(
client_id, client_secret, ['read_prefs', 'write_map']
).auth_code()
api = osmapi.OsmApi(
api="https://api06.dev.openstreetmap.org",
session=auth.session
)
with api.Changeset({"comment": "My first test"}) as changeset_id:
print(f"Part of Changeset {changeset_id}")
node1 = api.NodeCreate({"lon": 1, "lat": 1, "tag": {}})
print(node1)
```
An alternative way using the `requests-oauthlib` library can be found
[in the examples](https://github.com/metaodi/osmapi/blob/develop/examples/oauth2.py).
## Note about imports / automated edits
Scripted imports and automated edits should only be carried out by those with experience and understanding of the way the OpenStreetMap community creates maps, and only with careful **planning** and **consultation** with the local community.
See the [Import/Guidelines](http://wiki.openstreetmap.org/wiki/Import/Guidelines) and [Automated Edits/Code of Conduct](http://wiki.openstreetmap.org/wiki/Automated_Edits/Code_of_Conduct) for more information.
## Development
If you want to help with the development of `osmapi`, you should clone this repository and install the requirements:
make deps
Better yet use the provided [`setup.sh`](https://github.com/metaodi/osmapi/blob/develop/setup.sh) script to create a virtual env and install this package in it.
You can lint the source code using this command:
make lint
And if you want to reformat the files (using the black code style) simply run:
make format
To run the tests use the following command:
make test
## Release
To create a new release, follow these steps (please respect [Semantic Versioning](http://semver.org/)):
1. Adapt the version number in `osmapi/__init__.py`
1. Update the CHANGELOG with the version
1. Re-build the documentation (`make docs`)
1. Create a pull request to merge develop into master (make sure the tests pass!)
1. Create a [new release/tag on GitHub](https://github.com/metaodi/osmapi/releases) (on the master branch)
1. The [publication on PyPI](https://pypi.python.org/pypi/osmapi) happens via [GitHub Actions](https://github.com/metaodi/osmapi/actions/workflows/publish_python.yml) on every tagged commit
## Attribution
This project was orginally developed by Etienne Chové.
This repository is a copy of the original code from SVN (http://svn.openstreetmap.org/applications/utils/python_lib/OsmApi/OsmApi.py), with the goal to enable easy contribution via GitHub and release of this package via [PyPI](https://pypi.python.org/pypi/osmapi).
See also the OSM wiki: http://wiki.openstreetmap.org/wiki/Osmapi
Raw data
{
"_id": null,
"home_page": "https://github.com/metaodi/osmapi",
"name": "osmapi",
"maintainer": "Stefan Oderbolz",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "odi@metaodi.ch",
"keywords": "openstreetmap, osm, api",
"author": "Etienne Chov\u00e9",
"author_email": "chove@crans.org",
"download_url": "https://files.pythonhosted.org/packages/10/c5/40121b4adea894a94254b93d5ea0e3a386e7d378f0612c0b0fc85bfd24b5/osmapi-4.2.0.tar.gz",
"platform": null,
"description": "osmapi\n======\n\n[](https://github.com/metaodi/osmapi/actions/workflows/build.yml)\n[](https://pypi.python.org/pypi/osmapi/)\n[](https://github.com/metaodi/osmapi/blob/master/LICENSE.txt)\n[](https://coveralls.io/r/metaodi/osmapi?branch=develop)\n[](https://github.com/psf/black)\n[](https://github.com/pre-commit/pre-commit)\n\n\nPython wrapper for the OSM API (requires Python >= 3.8)\n\n## Installation\n\nInstall [`osmapi` from PyPi](https://pypi.python.org/pypi/osmapi) by using pip: \n\n pip install osmapi\n\n## Documentation\n\nThe documentation is generated using `pdoc` and can be [viewed online](http://osmapi.metaodi.ch).\n\nThe build the documentation locally, you can use\n\n make docs\n\nThis project uses GitHub Pages to publish its documentation.\nTo update the online documentation, you need to re-generate the documentation with the above command and update the `master` branch of this repository.\n\n## Examples\n\nTo test this library, please create an account on the [development server of OpenStreetMap (https://api06.dev.openstreetmap.org)](https://api06.dev.openstreetmap.org).\n\nCheck the [examples directory](https://github.com/metaodi/osmapi/tree/develop/examples) to find more example code.\n\n### Read from OpenStreetMap\n\n```python\n>>> import osmapi\n>>> api = osmapi.OsmApi()\n>>> print(api.NodeGet(123))\n{u'changeset': 532907, u'uid': 14298,\nu'timestamp': u'2007-09-29T09:19:17Z',\nu'lon': 10.790009299999999, u'visible': True,\nu'version': 1, u'user': u'Mede',\nu'lat': 59.9503044, u'tag': {}, u'id': 123}\n```\n\n### Constructor\n\n```python\nimport osmapi\napi = osmapi.OsmApi(api=\"https://api06.dev.openstreetmap.org\", username = \"you\", password = \"***\")\napi = osmapi.OsmApi(username = \"you\", passwordfile = \"/etc/mypasswords\")\napi = osmapi.OsmApi(passwordfile = \"/etc/mypasswords\") # if only the passwordfile is specified, the credentials on the first line of the file will be used\n```\n\nNote: Each line in the password file should have the format _user:password_\n\n### Write to OpenStreetMap\n\n```python\n>>> import osmapi\n>>> api = osmapi.OsmApi(api=\"https://api06.dev.openstreetmap.org\", username = u\"metaodi\", password = u\"*******\")\n>>> api.ChangesetCreate({u\"comment\": u\"My first test\"})\n>>> print(api.NodeCreate({u\"lon\":1, u\"lat\":1, u\"tag\": {}}))\n{u'changeset': 532907, u'lon': 1, u'version': 1, u'lat': 1, u'tag': {}, u'id': 164684}\n>>> api.ChangesetClose()\n```\n\n### OAuth authentication\n\nUsername/Password authentication will be deprecated in July 2024\n(see [official OWG announcemnt](https://blog.openstreetmap.org/2024/04/17/oauth-1-0a-and-http-basic-auth-shutdown-on-openstreetmap-org/) for details).\nIn order to use this library in the future, you'll need to use OAuth 2.0.\n\nTo use OAuth 2.0, you must register an application with an OpenStreetMap account, either on the\n[development server](https://master.apis.dev.openstreetmap.org/oauth2/applications)\nor on the [production server](https://www.openstreetmap.org/oauth2/applications).\nOnce this registration is done, you'll get a `client_id` and a `client_secret` that you can use to authenticate users.\n\nExample code using [`cli-oauth2`](https://github.com/Zverik/cli-oauth2) on the development server, replace `OpenStreetMapDevAuth` with `OpenStreetMapAuth` to use the production server:\n\n```python\nimport osmapi\nfrom oauthcli import OpenStreetMapDevAuth\n\nclient_id = \"<client_id>\"\nclient_secret = \"<client_secret>\"\n\nauth = OpenStreetMapDevAuth(\n client_id, client_secret, ['read_prefs', 'write_map']\n).auth_code()\n\napi = osmapi.OsmApi(\n api=\"https://api06.dev.openstreetmap.org\",\n session=auth.session\n)\n\nwith api.Changeset({\"comment\": \"My first test\"}) as changeset_id:\n print(f\"Part of Changeset {changeset_id}\")\n node1 = api.NodeCreate({\"lon\": 1, \"lat\": 1, \"tag\": {}})\n print(node1)\n```\n\nAn alternative way using the `requests-oauthlib` library can be found\n[in the examples](https://github.com/metaodi/osmapi/blob/develop/examples/oauth2.py).\n\n## Note about imports / automated edits\n\nScripted imports and automated edits should only be carried out by those with experience and understanding of the way the OpenStreetMap community creates maps, and only with careful **planning** and **consultation** with the local community.\n\nSee the [Import/Guidelines](http://wiki.openstreetmap.org/wiki/Import/Guidelines) and [Automated Edits/Code of Conduct](http://wiki.openstreetmap.org/wiki/Automated_Edits/Code_of_Conduct) for more information.\n\n## Development\n\nIf you want to help with the development of `osmapi`, you should clone this repository and install the requirements:\n\n make deps\n\nBetter yet use the provided [`setup.sh`](https://github.com/metaodi/osmapi/blob/develop/setup.sh) script to create a virtual env and install this package in it. \n\nYou can lint the source code using this command:\n\n make lint\n\nAnd if you want to reformat the files (using the black code style) simply run:\n\n make format\n\nTo run the tests use the following command:\n\n make test\n\n## Release\n\nTo create a new release, follow these steps (please respect [Semantic Versioning](http://semver.org/)):\n\n1. Adapt the version number in `osmapi/__init__.py`\n1. Update the CHANGELOG with the version\n1. Re-build the documentation (`make docs`)\n1. Create a pull request to merge develop into master (make sure the tests pass!)\n1. Create a [new release/tag on GitHub](https://github.com/metaodi/osmapi/releases) (on the master branch)\n1. The [publication on PyPI](https://pypi.python.org/pypi/osmapi) happens via [GitHub Actions](https://github.com/metaodi/osmapi/actions/workflows/publish_python.yml) on every tagged commit\n\n## Attribution\n\nThis project was orginally developed by Etienne Chov\u00e9.\nThis repository is a copy of the original code from SVN (http://svn.openstreetmap.org/applications/utils/python_lib/OsmApi/OsmApi.py), with the goal to enable easy contribution via GitHub and release of this package via [PyPI](https://pypi.python.org/pypi/osmapi).\n\nSee also the OSM wiki: http://wiki.openstreetmap.org/wiki/Osmapi\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Python wrapper for the OSM API",
"version": "4.2.0",
"project_urls": {
"Download": "https://github.com/metaodi/osmapi/archive/v4.2.0.zip",
"Homepage": "https://github.com/metaodi/osmapi"
},
"split_keywords": [
"openstreetmap",
" osm",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "93672184de541fd4547c52ba701b12e0762a413ce9f36337c42be94eb94139d8",
"md5": "c8e27042c23711242cafedd240c5d696",
"sha256": "e6b269aa0653939dd3347b54d37f535d60b0ed37700cf417650ddbdb0b381331"
},
"downloads": -1,
"filename": "osmapi-4.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8e27042c23711242cafedd240c5d696",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 47108,
"upload_time": "2024-08-08T07:03:20",
"upload_time_iso_8601": "2024-08-08T07:03:20.776417Z",
"url": "https://files.pythonhosted.org/packages/93/67/2184de541fd4547c52ba701b12e0762a413ce9f36337c42be94eb94139d8/osmapi-4.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "10c540121b4adea894a94254b93d5ea0e3a386e7d378f0612c0b0fc85bfd24b5",
"md5": "99fe2ea1d4eea9eda539877fc36760ef",
"sha256": "eef8aff6dfedfda41e523859c6d4e9cd1b5b91943354b76564b63fc4c299c22f"
},
"downloads": -1,
"filename": "osmapi-4.2.0.tar.gz",
"has_sig": false,
"md5_digest": "99fe2ea1d4eea9eda539877fc36760ef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 43771,
"upload_time": "2024-08-08T07:03:22",
"upload_time_iso_8601": "2024-08-08T07:03:22.053468Z",
"url": "https://files.pythonhosted.org/packages/10/c5/40121b4adea894a94254b93d5ea0e3a386e7d378f0612c0b0fc85bfd24b5/osmapi-4.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-08 07:03:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "metaodi",
"github_project": "osmapi",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "pdoc",
"specs": [
[
"==",
"14.5.1"
]
]
},
{
"name": "Pygments",
"specs": [
[
"==",
"2.15.0"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.0"
]
]
},
{
"name": "python-dotenv",
"specs": []
}
],
"lcname": "osmapi"
}
JSON
