# Geolocate
Georeferencing large amounts of data for free.
Special thanks to @brunodepauloalmeida and the whole team for the contributions.
## How?
It's using the very same API that Waze uses to georeference addresses before
it finds the best route to that destination. It requires no API keys, works
really well and has fairly high throughput.
In order to make this package extensible, there's an abstract class
`GeolocateEngine` that defines the interface for the engines. This allows
for the addition of new engines without having to modify the code.
## How do I use it?
First you have to install the `geolocate` package for Python 3.7+:
```
pip3 install geolocate
```
Then, for a single address:
```py
>>> from geolocate import geolocate
>>> geolocate("1 Infinite Loop, Cupertino, CA 95014")
{'latitude': 37.3311841, 'longitude': -122.0287127}
```
Or, if you want to run things in parallel:
```py
>>> from geolocate import geolocate_batch
>>> geolocate_batch(["1 Infinite Loop, Cupertino, CA 95014", "Eiffel Tower"])
100%|███████| 2/2 [00:01<00:00, 1.66it/s]
[{'latitude': 37.3311841, 'longitude': -122.0287127}, {'latitude': 48.8560934, 'longitude': 2.2930458}]
```
### Advanced usage
Both `geolocate` and `geolocate_batch` accept the following keyword arguments:
- engine (`geolocate.engines.GeolocateEngine`): Engine to use for
geolocating the address. Defaults to `geolocate.engines.WazeEngine`
- timeout (int): The timeout in seconds.
- tries (int): The number of attempts to geolocate the address.
- backoff_factor (float): The backoff factor. Delay will grow by
`{backoff factor} * (2 ** ({number of total retries} - 1))`.
- on_not_found (str or callable): A callback function for when the
address is not found. The signature of the callback function
should be:
```py
def callback(address: str):
...
```
where `address` is the address that was not found. The return
value of the callback function is returned by the geolocate
function.
- on_error (str or callable): A callback function for when an error
occurs. The signature of the callback function should be:
```py
def callback(address: str, error: Exception):
...
```
where `address` is the address that caused the error and
`error` is the exception that occurred. The return value of
the callback function is returned by the geolocate function.
In addition, the `geolocate_batch` function accepts the following
keyword arguments:
- num_cpus (int): The number of CPUs to use. If None, the number of
CPUs will be determined automatically.
Raw data
{
"_id": null,
"home_page": "https://github.com/gabriel-milan/geolocate",
"name": "geolocate",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "geocode,geolocate,georeferencing",
"author": "Gabriel Gazola Milan",
"author_email": "gabriel.gazola@poli.ufrj.br",
"download_url": "https://files.pythonhosted.org/packages/ef/37/a9cf8dafea951dba7261558644b4b7a6c6d071b920fa25ed01ccf774efe5/geolocate-0.1.2.tar.gz",
"platform": null,
"description": "# Geolocate\n\nGeoreferencing large amounts of data for free.\n\nSpecial thanks to @brunodepauloalmeida and the whole team for the contributions.\n\n## How?\n\nIt's using the very same API that Waze uses to georeference addresses before\nit finds the best route to that destination. It requires no API keys, works\nreally well and has fairly high throughput.\n\nIn order to make this package extensible, there's an abstract class\n`GeolocateEngine` that defines the interface for the engines. This allows\nfor the addition of new engines without having to modify the code.\n\n## How do I use it?\n\nFirst you have to install the `geolocate` package for Python 3.7+:\n\n```\npip3 install geolocate\n```\n\nThen, for a single address:\n\n```py\n>>> from geolocate import geolocate\n>>> geolocate(\"1 Infinite Loop, Cupertino, CA 95014\")\n{'latitude': 37.3311841, 'longitude': -122.0287127}\n```\n\nOr, if you want to run things in parallel:\n\n```py\n>>> from geolocate import geolocate_batch\n>>> geolocate_batch([\"1 Infinite Loop, Cupertino, CA 95014\", \"Eiffel Tower\"])\n100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 2/2 [00:01<00:00, 1.66it/s]\n[{'latitude': 37.3311841, 'longitude': -122.0287127}, {'latitude': 48.8560934, 'longitude': 2.2930458}]\n```\n\n### Advanced usage\n\nBoth `geolocate` and `geolocate_batch` accept the following keyword arguments:\n\n- engine (`geolocate.engines.GeolocateEngine`): Engine to use for\n geolocating the address. Defaults to `geolocate.engines.WazeEngine`\n- timeout (int): The timeout in seconds.\n- tries (int): The number of attempts to geolocate the address.\n- backoff_factor (float): The backoff factor. Delay will grow by\n `{backoff factor} * (2 ** ({number of total retries} - 1))`.\n- on_not_found (str or callable): A callback function for when the\n address is not found. The signature of the callback function\n should be:\n ```py\n def callback(address: str):\n ...\n ```\n where `address` is the address that was not found. The return\n value of the callback function is returned by the geolocate\n function.\n- on_error (str or callable): A callback function for when an error\n occurs. The signature of the callback function should be:\n ```py\n def callback(address: str, error: Exception):\n ...\n ```\n where `address` is the address that caused the error and\n `error` is the exception that occurred. The return value of\n the callback function is returned by the geolocate function.\n\nIn addition, the `geolocate_batch` function accepts the following\nkeyword arguments:\n\n- num_cpus (int): The number of CPUs to use. If None, the number of\n CPUs will be determined automatically.\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Georeferencing large amounts of data for free.",
"version": "0.1.2",
"split_keywords": [
"geocode",
"geolocate",
"georeferencing"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "2f6b0a2aad47ce7ff402244c234be3af",
"sha256": "5d3417a3711c3aea362d7fb08476ac82e4b8dd2f94e9bc7a0ae246cea0b993b1"
},
"downloads": -1,
"filename": "geolocate-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f6b0a2aad47ce7ff402244c234be3af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 20275,
"upload_time": "2022-12-07T11:49:43",
"upload_time_iso_8601": "2022-12-07T11:49:43.990146Z",
"url": "https://files.pythonhosted.org/packages/1e/b9/d8050cd33aec221fdc993b2db4897e33778eba5b59c33a4a26bbf40ed07a/geolocate-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "c6a3a5f7af8658d37754bb5507f9e329",
"sha256": "0fab141353380ede2e4b7ab87eb85f54c34ef8854e9360caada7deb9d1bfa187"
},
"downloads": -1,
"filename": "geolocate-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "c6a3a5f7af8658d37754bb5507f9e329",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 17401,
"upload_time": "2022-12-07T11:49:45",
"upload_time_iso_8601": "2022-12-07T11:49:45.026083Z",
"url": "https://files.pythonhosted.org/packages/ef/37/a9cf8dafea951dba7261558644b4b7a6c6d071b920fa25ed01ccf774efe5/geolocate-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-07 11:49:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "gabriel-milan",
"github_project": "geolocate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "geolocate"
}
JSON
