# <img src="https://what3words.com/assets/images/w3w_square_red.png" width="64" height="64" alt="what3words"> w3w-python-wrapper [](https://travis-ci.org/what3words/w3w-python-wrapper)
A Python library to use the [what3words REST API](https://docs.what3words.com/api/v3/).
Tested with Python 2.7, 3.4, 3.5, 3.6 (check travis-ci.org [build](https://travis-ci.org/what3words/w3w-python-wrapper/builds))
# Overview
The what3words Python library gives you programmatic access to
* convert a 3 word address to coordinates
* convert coordinates to a 3 word address
* autosuggest functionality which takes a slightly incorrect 3 word address, and suggests a list of valid 3 word addresses
* obtain a section of the 3m x 3m what3words grid for a bounding box.
* determine the currently support 3 word address languages.
## Authentication
To use this library you’ll need an API key, please visit [https://what3words.com/select-plan](https://what3words.com/select-plan) and sign up for an account.
# Installation
## PyPi Install
To install what3words, simply:
```bash
$ pip install what3words
```
## GitHub Install
Installing the latest version from Github:
```bash
$ git clone https://github.com/what3words/w3w-python-wrapper.git
$ cd w3w-python-wrapper
$ python setup.py install
```
## Convert To Coordinates
This function takes the words parameter as a string of 3 words `'table.book.chair'`
The returned payload from the `convert-to-coordinates` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#convert-to-coordinates).
## Convert To 3 Word Address
This function takes the latitude and longitude:
- 2 parameters: `lat=0.1234`, `lng=1.5678`
The returned payload from the `convert-to-3wa` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#convert-to-3wa).
## AutoSuggest
Returns a list of 3 word addresses based on user input and other parameters.
This method provides corrections for the following types of input error:
* typing errors
* spelling errors
* misremembered words (e.g. singular vs. plural)
* words in the wrong order
The `autosuggest` method determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions. This method can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.
### Input 3 word address
You will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned.
### Clipping and Focus
We provide various `clip` policies to allow you to specify a geographic area that is used to exclude results that are not likely to be relevant to your users. We recommend that you use the `clip` parameter to give a more targeted, shorter set of results to your user. If you know your user’s current location, we also strongly recommend that you use the `focus` to return results which are likely to be more relevant.
In summary, the `clip` policy is used to optionally restrict the list of candidate AutoSuggest results, after which, if focus has been supplied, this will be used to rank the results in order of relevancy to the focus.
https://docs.what3words.com/api/v3/#autosuggest
The returned payload from the `autosuggest` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#autosuggest).
## Grid Section
Returns a section of the 3m x 3m what3words grid for a bounding box.
## Available Languages
Retrieves a list of the currently loaded and available 3 word address languages.
The returned payload from the `available-languages` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#available-languages).
## is_possible_3wa
This method takes a string as a parameter and returns whether the string is in the format of a 3WA (eg “filled.count.soap”). Return type is boolean. NOTE: Does not check if it is an actual existing 3WA.
```
is_possible_3wa(“filled.count.soap”) returns True
is_possible_3wa(“not a 3wa”) returns False
is_possible_3wa(“not.3wa address”) returns False
```
## find_possible_3wa
This method takes a string as a parameter and searches the string for any possible instances of a 3WA - e.g. "leave in my porch at word.word.word." Likely to be the main method that is called on the delivery notes. Returns an array of matched items. Returns an empty array if no matches are found. NOTE: Does not check if it is an actual existing 3WA.
```
find_possible_3wa(“Please leave by my porch at filled.count.soap”) will return [‘filled.count.soap’]
find_possible_3wa(“Please leave by my porch at filled.count.soap or deed.tulip.judge”) will return [‘filled.count.soap’, ‘deed.tulip.judge’]
find_possible_3wa(“Please leave by my porch at”) will return []
```
## is_valid_3wa
This method takes a string as a parameter and first passes it through the W3W regex filter (akin to calling is_possible_3wa() on the string) and then calls the W3W api to verify it is a real 3WA.
```
is_valid_3wa(“filled.count.soap”) returns True
is_valid_3wa(“filled.count.”) returns False
is_valid_3wa(“python.is.cool”) returns False
```
## Code examples
### W3W-API-KEY
For safe storage of your API key on your computer, you can define that API key using your system’s environment variables.
```bash
$ export W3W_API_KEY=<Secret API Key>
```
### Convert to coordinates
```python
import what3words
from os import environ
api_key = environ['W3W_API_KEY']
w3w = what3words.Geocoder(api_key)
res = w3w.convert_to_coordinates('prom.cape.pump')
print(res)
```
### Convert to 3 word address
```python
import what3words
from os import environ
api_key = environ['W3W_API_KEY']
w3w = what3words.Geocoder(api_key)
res = w3w.convert_to_3wa(what3words.Coordinates(51.484463,-0.195405))
print(res)
```
## Issues
Find a bug or want to request a new feature? Please let us know by submitting an issue.
## Contributing
Anyone and everyone is welcome to contribute.
1. Fork it (https://github.com/what3words/w3w-python-wrapper and click "Fork")
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
# Revision History
* `v3.4.0` 28/11/24 - Support locale for the autosuggest and update the readme file
* `v3.3.0` 30/09/24 - Support locale, update regex, format and tests
* `v3.2.0` 08/03/22 - Added regex functions
* `v3.1.1` 04/10/19 - Fix bugs related to setting default language value, and autosuggest input-type
* `v3.1.0` 29/08/19 - Support 'prefer-land' parameter for Autosuggest calls
* `v3.0.2` 16/07/19 - Include User-Agent in API requests
* `v3.0.0` 04/02/19 - Updated wrapper to use what3words API v3
* `v2.2.1` 08/09/17 - Python 3 setup install fixed thanks to [@joedborg](https://github.com/joedborg)
* `v2.2.0` 07/09/17 - Python 3 support, thanks to [@joedborg](https://github.com/joedborg)
* `v2.1.1` 07/09/17 - update README : this library is compatible with Python 2
* `v2.1.0` 28/03/17 - Added multilingual version of `autosuggest` and `standardblend`
* `v2.0.2` 27/10/16 - Published on PyPi
* `v2.0.0` 10/06/16 - Updated wrapper to use what3words API v2
## Licensing
The MIT License (MIT)
A copy of the license is available in the repository's [license](LICENSE) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/what3words/w3w-python-wrapper",
"name": "what3words",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "what3words geocoder",
"author": "what3words",
"author_email": "support@what3words.com",
"download_url": "https://files.pythonhosted.org/packages/60/f1/c06c953b377596da0b7c70fe138fef8f66ba6046f44586e6bbcffa7ca711/what3words-3.4.0.tar.gz",
"platform": null,
"description": "# <img src=\"https://what3words.com/assets/images/w3w_square_red.png\" width=\"64\" height=\"64\" alt=\"what3words\"> w3w-python-wrapper [](https://travis-ci.org/what3words/w3w-python-wrapper)\n\nA Python library to use the [what3words REST API](https://docs.what3words.com/api/v3/).\n\nTested with Python 2.7, 3.4, 3.5, 3.6 (check travis-ci.org [build](https://travis-ci.org/what3words/w3w-python-wrapper/builds))\n\n# Overview\n\nThe what3words Python library gives you programmatic access to \n* convert a 3 word address to coordinates \n* convert coordinates to a 3 word address\n* autosuggest functionality which takes a slightly incorrect 3 word address, and suggests a list of valid 3 word addresses\n* obtain a section of the 3m x 3m what3words grid for a bounding box.\n* determine the currently support 3 word address languages.\n\n## Authentication\n\nTo use this library you\u2019ll need an API key, please visit [https://what3words.com/select-plan](https://what3words.com/select-plan) and sign up for an account.\n\n# Installation\n\n## PyPi Install\n\nTo install what3words, simply:\n\n```bash\n$ pip install what3words\n```\n\n## GitHub Install\n\nInstalling the latest version from Github:\n\n```bash\n$ git clone https://github.com/what3words/w3w-python-wrapper.git\n$ cd w3w-python-wrapper\n$ python setup.py install\n```\n\n## Convert To Coordinates\n\nThis function takes the words parameter as a string of 3 words `'table.book.chair'`\n\nThe returned payload from the `convert-to-coordinates` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#convert-to-coordinates).\n\n## Convert To 3 Word Address\n\nThis function takes the latitude and longitude:\n- 2 parameters: `lat=0.1234`, `lng=1.5678`\n\nThe returned payload from the `convert-to-3wa` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#convert-to-3wa).\n\n\n## AutoSuggest\n\nReturns a list of 3 word addresses based on user input and other parameters.\n\nThis method provides corrections for the following types of input error:\n* typing errors\n* spelling errors\n* misremembered words (e.g. singular vs. plural)\n* words in the wrong order\n\nThe `autosuggest` method determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions. This method can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.\n\n### Input 3 word address\n\nYou will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned.\n\n### Clipping and Focus\n\nWe provide various `clip` policies to allow you to specify a geographic area that is used to exclude results that are not likely to be relevant to your users. We recommend that you use the `clip` parameter to give a more targeted, shorter set of results to your user. If you know your user\u2019s current location, we also strongly recommend that you use the `focus` to return results which are likely to be more relevant.\n\nIn summary, the `clip` policy is used to optionally restrict the list of candidate AutoSuggest results, after which, if focus has been supplied, this will be used to rank the results in order of relevancy to the focus.\n\nhttps://docs.what3words.com/api/v3/#autosuggest\n\nThe returned payload from the `autosuggest` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#autosuggest).\n\n## Grid Section\n\nReturns a section of the 3m x 3m what3words grid for a bounding box.\n\n## Available Languages\n\nRetrieves a list of the currently loaded and available 3 word address languages.\n\nThe returned payload from the `available-languages` method is described in the [what3words REST API documentation](https://docs.what3words.com/api/v3/#available-languages).\n\n\n## is_possible_3wa\nThis method takes a string as a parameter and returns whether the string is in the format of a 3WA (eg \u201cfilled.count.soap\u201d). Return type is boolean. NOTE: Does not check if it is an actual existing 3WA. \n\n```\nis_possible_3wa(\u201cfilled.count.soap\u201d) returns True\nis_possible_3wa(\u201cnot a 3wa\u201d) returns False\nis_possible_3wa(\u201cnot.3wa address\u201d) returns False\n```\n\n## find_possible_3wa\n\nThis method takes a string as a parameter and searches the string for any possible instances of a 3WA - e.g. \"leave in my porch at word.word.word.\" Likely to be the main method that is called on the delivery notes. Returns an array of matched items. Returns an empty array if no matches are found. NOTE: Does not check if it is an actual existing 3WA.\n\n```\nfind_possible_3wa(\u201cPlease leave by my porch at filled.count.soap\u201d) will return [\u2018filled.count.soap\u2019]\nfind_possible_3wa(\u201cPlease leave by my porch at filled.count.soap or deed.tulip.judge\u201d) will return [\u2018filled.count.soap\u2019, \u2018deed.tulip.judge\u2019]\nfind_possible_3wa(\u201cPlease leave by my porch at\u201d) will return []\n```\n\n## is_valid_3wa\n\nThis method takes a string as a parameter and first passes it through the W3W regex filter (akin to calling is_possible_3wa() on the string) and then calls the W3W api to verify it is a real 3WA.\n\n```\nis_valid_3wa(\u201cfilled.count.soap\u201d) returns True\nis_valid_3wa(\u201cfilled.count.\u201d) returns False\nis_valid_3wa(\u201cpython.is.cool\u201d) returns False\n```\n\n## Code examples\n\n### W3W-API-KEY\nFor safe storage of your API key on your computer, you can define that API key using your system\u2019s environment variables.\n```bash\n$ export W3W_API_KEY=<Secret API Key>\n```\n\n### Convert to coordinates\n```python\nimport what3words\nfrom os import environ\napi_key = environ['W3W_API_KEY']\nw3w = what3words.Geocoder(api_key)\nres = w3w.convert_to_coordinates('prom.cape.pump')\nprint(res)\n```\n\n### Convert to 3 word address\n```python\nimport what3words\nfrom os import environ\napi_key = environ['W3W_API_KEY']\nw3w = what3words.Geocoder(api_key)\nres = w3w.convert_to_3wa(what3words.Coordinates(51.484463,-0.195405))\nprint(res)\n```\n\n## Issues\n\nFind a bug or want to request a new feature? Please let us know by submitting an issue.\n\n## Contributing\nAnyone and everyone is welcome to contribute.\n\n1. Fork it (https://github.com/what3words/w3w-python-wrapper and click \"Fork\")\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n\n# Revision History\n* `v3.4.0` 28/11/24 - Support locale for the autosuggest and update the readme file\n* `v3.3.0` 30/09/24 - Support locale, update regex, format and tests\n* `v3.2.0` 08/03/22 - Added regex functions\n* `v3.1.1` 04/10/19 - Fix bugs related to setting default language value, and autosuggest input-type\n* `v3.1.0` 29/08/19 - Support 'prefer-land' parameter for Autosuggest calls\n* `v3.0.2` 16/07/19 - Include User-Agent in API requests\n* `v3.0.0` 04/02/19 - Updated wrapper to use what3words API v3\n* `v2.2.1` 08/09/17 - Python 3 setup install fixed thanks to [@joedborg](https://github.com/joedborg)\n* `v2.2.0` 07/09/17 - Python 3 support, thanks to [@joedborg](https://github.com/joedborg)\n* `v2.1.1` 07/09/17 - update README : this library is compatible with Python 2\n* `v2.1.0` 28/03/17 - Added multilingual version of `autosuggest` and `standardblend`\n* `v2.0.2` 27/10/16 - Published on PyPi\n* `v2.0.0` 10/06/16 - Updated wrapper to use what3words API v2\n\n## Licensing\n\nThe MIT License (MIT)\n\nA copy of the license is available in the repository's [license](LICENSE) file.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "what3words Python API wrapper library",
"version": "3.4.0",
"project_urls": {
"Homepage": "https://github.com/what3words/w3w-python-wrapper"
},
"split_keywords": [
"what3words",
"geocoder"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dc30af754568503817b9384082e725b59acd222ae2ae649516d1bf2db8de4c42",
"md5": "48c436e60eccdcd08e0213ae7b7a3c0a",
"sha256": "818348742a279a9f002b22e83e50c85d20856fd318db9b44f086c37ca16097fb"
},
"downloads": -1,
"filename": "what3words-3.4.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "48c436e60eccdcd08e0213ae7b7a3c0a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 8679,
"upload_time": "2024-11-28T19:19:33",
"upload_time_iso_8601": "2024-11-28T19:19:33.062643Z",
"url": "https://files.pythonhosted.org/packages/dc/30/af754568503817b9384082e725b59acd222ae2ae649516d1bf2db8de4c42/what3words-3.4.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "60f1c06c953b377596da0b7c70fe138fef8f66ba6046f44586e6bbcffa7ca711",
"md5": "af64fba52bbbb728335dea0a6c946e03",
"sha256": "74403fae6aea2d0306f2f001516e9b86a4975491e8f5f5ff2bdf04307f4554a4"
},
"downloads": -1,
"filename": "what3words-3.4.0.tar.gz",
"has_sig": false,
"md5_digest": "af64fba52bbbb728335dea0a6c946e03",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11324,
"upload_time": "2024-11-28T19:19:34",
"upload_time_iso_8601": "2024-11-28T19:19:34.871045Z",
"url": "https://files.pythonhosted.org/packages/60/f1/c06c953b377596da0b7c70fe138fef8f66ba6046f44586e6bbcffa7ca711/what3words-3.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-28 19:19:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "what3words",
"github_project": "w3w-python-wrapper",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"circle": true,
"requirements": [],
"lcname": "what3words"
}
JSON
