# HERE Location Services for Python
[](https://github.com/heremaps/here-location-services-python/actions)
[](https://here-location-services-python.readthedocs.io/en/stable/?badge=stable)
[](https://codecov.io/gh/heremaps/here-location-services-python)
[](https://pypi.org/project/here-location-services/)
[](https://pypi.org/project/here-location-services/)
[](https://pypi.org/project/here-location-services/)
[](https://pypi.org/project/here-location-services/)
[](https://pepy.tech/project/here-location-services)
[](https://anaconda.org/conda-forge/here-location-services)
[](https://anaconda.org/conda-forge/here-location-services)
[](https://anaconda.org/conda-forge/here-location-services)
[](https://mybinder.org/v2/gh/heremaps/here-location-services-python/master?urlpath=lab/tree/docs/notebooks)
A Python client for [HERE Location Services](https://developer.here.com/documentation#services).
## Usage
**[Geocoding using HERE Geocoding & Search API](https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/endpoint-geocode-brief.html).**
# 
**[Isolines using HERE Isoline Routing API](https://developer.here.com/documentation/isoline-routing-api/dev_guide/index.html).**
# 
## Prerequisites
Before you can install `HERE Location Services for Python`, run its test-suite, or use the example notebooks to make sure you meet the following prerequisites:
- A Python installation, 3.6+ recommended, with the `pip` command available to install dependencies.
- In order to use Location services APIs, authentication is required.
There are two ways to authenticate:
- Authentication using an API key:
- For API key-based authentication you will need a HERE developer account, freely available under [HERE Developer Portal](https://developer.here.com).
- An [API key](https://developer.here.com/documentation/identity-access-management/dev_guide/topics/dev-apikey.html) from the [HERE Developer Portal](https://developer.here.com), in an environment variable named `LS_API_KEY` which you can set like this (with a valid value, of course):
```bash
$ export LS_API_KEY="MY-LS-API-KEY"
```
- OAuth token-based authentication:
- For OAuth token authentication you will need an account on the HERE Platform.
To get more details on the HERE Platform account please check our documentation [Get a HERE account](https://developer.here.com/documentation/identity-access-management/dev_guide/topics/obtain-user-credentials.html).
Once you have the account follow the below steps to get credentials:
- Go to [HERE Platform Applications and Keys](https://platform.here.com/profile/apps-and-keys) and register a new app.
- Create a key for the app and download the generated `credentials. properties` file.
The HERE platform generated app credentials should look similar to the example below:
```
here.user.id = <example_here>
here.client.id = <example_here>
here.access.key.id = <example_here>
here.access.key.secret = <example_here>
here.token.endpoint.url = <example_here>
```
You can provide your credentials using any of the following methods:
- Default credentials
- Environment variables
- Credentials file
#### Default credentials
Place the credentials file into
For Linux/MacOS: `$HOME/.here/credentials.properties`
For Windows: `%USERPROFILE%\.here\credentials.properties`
Code snippet to instantiate LS object:
```python
from here_location_services import LS
# platform credentials will be picked from the default credentials file's location mentioned above
# and api_key should not be set in env variable LS_API_KEY.
ls = LS()
```
#### Environment Variables
You can override default credentials by assigning values to the following environment variables:
```
HERE_USER_ID
HERE_CLIENT_ID
HERE_ACCESS_KEY_ID
HERE_ACCESS_KEY_SECRET
HERE_TOKEN_ENDPOINT_URL
```
Code snippet to instantiate LS object:
```python
from here_location_services import LS
from here_location_services import PlatformCredentials
ls = LS(platform_credentials=PlatformCredentials.from_env())
```
#### Credentials File
You can specify any credentials file as an alternative to that found in `~/.here/credentials.properties`. An error is generated if there is no file present at the path, or if the file is not properly formatted.
Code snippet to instantiate LS object:
```python
from here_location_services import LS
from here_location_services import PlatformCredentials
platform_credentials = PlatformCredentials.from_credentials_file("<Path_to_file>")
ls = LS(platform_credentials=platform_credentials)
```
## Installation
- Install `HERE Location Services for Python` with conda from the Anaconda [conda-forge channel](https://anaconda.org/conda-forge/here-location-services) using the below command:
```bash
$ conda install -c conda-forge here-location-services
```
- Install `HERE Location Services for Python` from [PyPI](https://pypi.org/project/here-location-services/) using the below command:
```bash
$ pip install here-location-services
```
- Install `HERE Location Services for Python` from GitHub using the below command:
```bash
$ pip install -e git+https://github.com/heremaps/here-location-services-python#egg=here-location-services
```
## Run Test Suite
Run the test suite using below commands:
```bash
$ pip install -r requirements_dev.txt
$ pytest -v --cov=here_location_services tests
```
## Documentation
Documentation is available [here](https://here-location-services-python.readthedocs.io/en/stable/).
Run the below commands to build the docs locally:
```bash
$ pip install -e .
$ pip install -r requirements_dev.txt
$ sh scripts/build_docs.sh
```
## Hello World Example
The following are tiny "Hello World" like examples that you can run to have a successful first XYZ experience right after installation!
#### Using API key
```python
import json
import os
from here_location_services import LS
LS_API_KEY = os.environ.get("LS_API_KEY") # Get API KEY from environment.
ls = LS(api_key=LS_API_KEY)
address = "Invalidenstr 116, 10115 Berlin, Germany"
geo = ls.geocode(query=address)
print(json.dumps(geo.to_geojson(), indent=2, sort_keys=True))
```
#### Using OAuth token
```python
import json
from here_location_services import LS
from here_location_services import PlatformCredentials
credentials = PlatformCredentials.from_default()
ls = LS(platform_credentials=credentials)
address = "Invalidenstr 116, 10115 Berlin, Germany"
geo = ls.geocode(query=address)
print(json.dumps(geo.to_geojson(), indent=2, sort_keys=True))
```
# License
Copyright (C) 2019-2021 HERE Europe B.V.
See the [License](LICENSE) file at the root of this project for license details.
Raw data
{
"_id": null,
"home_page": "https://here.com",
"name": "here-location-services",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "API,REST,Client,Locaton Services",
"author": "HERE Europe B.V.",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/49/a0/edad803a3ec247f7db37070e4793ccc30b67ca935bebf0b78f3998d52958/here-location-services-0.4.0.tar.gz",
"platform": "any",
"description": "# HERE Location Services for Python\n\n[](https://github.com/heremaps/here-location-services-python/actions)\n[](https://here-location-services-python.readthedocs.io/en/stable/?badge=stable)\n[](https://codecov.io/gh/heremaps/here-location-services-python)\n[](https://pypi.org/project/here-location-services/)\n[](https://pypi.org/project/here-location-services/)\n[](https://pypi.org/project/here-location-services/)\n[](https://pypi.org/project/here-location-services/)\n[](https://pepy.tech/project/here-location-services)\n[](https://anaconda.org/conda-forge/here-location-services)\n[](https://anaconda.org/conda-forge/here-location-services)\n[](https://anaconda.org/conda-forge/here-location-services)\n[](https://mybinder.org/v2/gh/heremaps/here-location-services-python/master?urlpath=lab/tree/docs/notebooks)\n\nA Python client for [HERE Location Services](https://developer.here.com/documentation#services).\n\n## Usage\n**[Geocoding using HERE Geocoding & Search API](https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/endpoint-geocode-brief.html).**\n# \n**[Isolines using HERE Isoline Routing API](https://developer.here.com/documentation/isoline-routing-api/dev_guide/index.html).**\n# \n\n## Prerequisites\n\nBefore you can install `HERE Location Services for Python`, run its test-suite, or use the example notebooks to make sure you meet the following prerequisites:\n\n- A Python installation, 3.6+ recommended, with the `pip` command available to install dependencies.\n- In order to use Location services APIs, authentication is required. \n There are two ways to authenticate:\n - Authentication using an API key: \n - For API key-based authentication you will need a HERE developer account, freely available under [HERE Developer Portal](https://developer.here.com).\n - An [API key](https://developer.here.com/documentation/identity-access-management/dev_guide/topics/dev-apikey.html) from the [HERE Developer Portal](https://developer.here.com), in an environment variable named `LS_API_KEY` which you can set like this (with a valid value, of course):\n ```bash\n $ export LS_API_KEY=\"MY-LS-API-KEY\"\n ```\n - OAuth token-based authentication:\n - For OAuth token authentication you will need an account on the HERE Platform.\n To get more details on the HERE Platform account please check our documentation [Get a HERE account](https://developer.here.com/documentation/identity-access-management/dev_guide/topics/obtain-user-credentials.html).\n Once you have the account follow the below steps to get credentials:\n - Go to [HERE Platform Applications and Keys](https://platform.here.com/profile/apps-and-keys) and register a new app.\n - Create a key for the app and download the generated `credentials. properties` file.\n\n The HERE platform generated app credentials should look similar to the example below:\n ```\n here.user.id = <example_here>\n here.client.id = <example_here>\n here.access.key.id = <example_here>\n here.access.key.secret = <example_here>\n here.token.endpoint.url = <example_here>\n ```\n You can provide your credentials using any of the following methods:\n - Default credentials\n - Environment variables\n - Credentials file\n\n #### Default credentials\n Place the credentials file into\n\n For Linux/MacOS: `$HOME/.here/credentials.properties`\n\n For Windows: `%USERPROFILE%\\.here\\credentials.properties`\n Code snippet to instantiate LS object:\n ```python\n from here_location_services import LS\n\n # platform credentials will be picked from the default credentials file's location mentioned above\n # and api_key should not be set in env variable LS_API_KEY.\n ls = LS()\n ```\n\n #### Environment Variables\n You can override default credentials by assigning values to the following environment variables:\n ```\n HERE_USER_ID\n HERE_CLIENT_ID\n HERE_ACCESS_KEY_ID\n HERE_ACCESS_KEY_SECRET\n HERE_TOKEN_ENDPOINT_URL\n ```\n Code snippet to instantiate LS object:\n ```python\n from here_location_services import LS\n from here_location_services import PlatformCredentials\n\n ls = LS(platform_credentials=PlatformCredentials.from_env()) \n ```\n #### Credentials File\n You can specify any credentials file as an alternative to that found in `~/.here/credentials.properties`. An error is generated if there is no file present at the path, or if the file is not properly formatted.\n Code snippet to instantiate LS object:\n ```python\n from here_location_services import LS\n from here_location_services import PlatformCredentials\n\n platform_credentials = PlatformCredentials.from_credentials_file(\"<Path_to_file>\")\n ls = LS(platform_credentials=platform_credentials) \n ```\n\n## Installation\n\n- Install `HERE Location Services for Python` with conda from the Anaconda [conda-forge channel](https://anaconda.org/conda-forge/here-location-services) using the below command:\n\n ```bash\n $ conda install -c conda-forge here-location-services\n ```\n- Install `HERE Location Services for Python` from [PyPI](https://pypi.org/project/here-location-services/) using the below command:\n\n ```bash\n $ pip install here-location-services\n ```\n\n- Install `HERE Location Services for Python` from GitHub using the below command:\n\n ```bash\n $ pip install -e git+https://github.com/heremaps/here-location-services-python#egg=here-location-services\n ```\n\n## Run Test Suite\n\nRun the test suite using below commands:\n\n```bash\n$ pip install -r requirements_dev.txt\n$ pytest -v --cov=here_location_services tests\n```\n\n## Documentation\n\nDocumentation is available [here](https://here-location-services-python.readthedocs.io/en/stable/).\n\nRun the below commands to build the docs locally:\n\n```bash\n$ pip install -e .\n$ pip install -r requirements_dev.txt\n$ sh scripts/build_docs.sh\n```\n\n## Hello World Example\nThe following are tiny \"Hello World\" like examples that you can run to have a successful first XYZ experience right after installation!\n\n#### Using API key\n```python\nimport json\nimport os\n\nfrom here_location_services import LS\n\n\nLS_API_KEY = os.environ.get(\"LS_API_KEY\") # Get API KEY from environment.\nls = LS(api_key=LS_API_KEY)\n\naddress = \"Invalidenstr 116, 10115 Berlin, Germany\"\ngeo = ls.geocode(query=address)\nprint(json.dumps(geo.to_geojson(), indent=2, sort_keys=True))\n```\n#### Using OAuth token\n```python\nimport json\n\nfrom here_location_services import LS\nfrom here_location_services import PlatformCredentials\n\ncredentials = PlatformCredentials.from_default()\nls = LS(platform_credentials=credentials)\n\naddress = \"Invalidenstr 116, 10115 Berlin, Germany\"\ngeo = ls.geocode(query=address)\nprint(json.dumps(geo.to_geojson(), indent=2, sort_keys=True))\n```\n\n# License\nCopyright (C) 2019-2021 HERE Europe B.V.\n\nSee the [License](LICENSE) file at the root of this project for license details.\n\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "HERE Location Services for Python",
"version": "0.4.0",
"project_urls": {
"Bug Tracker": "https://github.com/heremaps/here-location-services-python/issues",
"Homepage": "https://here.com",
"Source": "https://github.com/heremaps/here-location-services-python"
},
"split_keywords": [
"api",
"rest",
"client",
"locaton services"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad9751ccf032afcf3b3273f5f12db76b03f3e276a1dafaa4f9a850ae81f3a2ac",
"md5": "ac2f05132e5fea85eedeb3ca88b43808",
"sha256": "1320ba23dcdef7d720f51f48037b664e380fef5e59f011832dd505738f4b649c"
},
"downloads": -1,
"filename": "here_location_services-0.4.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac2f05132e5fea85eedeb3ca88b43808",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 58094,
"upload_time": "2021-09-07T07:21:43",
"upload_time_iso_8601": "2021-09-07T07:21:43.981380Z",
"url": "https://files.pythonhosted.org/packages/ad/97/51ccf032afcf3b3273f5f12db76b03f3e276a1dafaa4f9a850ae81f3a2ac/here_location_services-0.4.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "49a0edad803a3ec247f7db37070e4793ccc30b67ca935bebf0b78f3998d52958",
"md5": "26725eabbeb37048884c8f986b4b9adf",
"sha256": "10523492f15e688e20b13763793171511c7fdfb9e44daef52774644cd6cbe7fb"
},
"downloads": -1,
"filename": "here-location-services-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "26725eabbeb37048884c8f986b4b9adf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 54896,
"upload_time": "2021-09-07T07:21:45",
"upload_time_iso_8601": "2021-09-07T07:21:45.119385Z",
"url": "https://files.pythonhosted.org/packages/49/a0/edad803a3ec247f7db37070e4793ccc30b67ca935bebf0b78f3998d52958/here-location-services-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-09-07 07:21:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "heremaps",
"github_project": "here-location-services-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "geojson",
"specs": []
},
{
"name": "flexpolyline",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "pyhocon",
"specs": []
},
{
"name": "requests_oauthlib",
"specs": []
}
],
"lcname": "here-location-services"
}
JSON
