Skip to content

Update README from master #442

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Snuffy2 merged 2 commits into from
Jul 12, 2026
Merged

Update README from master #442

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1afbfe1
Update README from master
Snuffy2 Jul 12, 2026
eb89a67
Update README.md
Snuffy2 Jul 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 49 additions & 75 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
<img alt="places Logo" src="https://github.com/custom-components/places/raw/master/logo/icon.png">
</picture>

[![Integration Usage][integration-usage-shield]][releases]

[![GitHub Downloads][downloads-shield]][releases]
[![GitHub Latest Downloads][downloads-latest-shield]][releases]
[![GitHub Release][releases-shield]][releases]
Expand All @@ -11,56 +13,46 @@
[![Coverage][coverage-shield]][coverage]
[![License][license-shield]](LICENSE)
[![hacs][hacsbadge]][hacs]
[![Community Forum][community-forum-shield]](community-forum)

_Component to integrate with OpenStreetMap Reverse Geocode and create a sensor with numerous address and place attributes from a device_tracker, person, or sensor_

## Installation
### HACS *(recommended)*
1. Ensure that [HACS](https://hacs.xyz/) is installed
1. [Click Here](https://my.home-assistant.io/redirect/hacs_repository/?owner=custom-components&repository=places) to directly open `places` in HACS **or**<br/>
  a. Navigate to HACS<br/>
  b. Click `+ Explore & Download Repositories`<br/>
  c. Find the `places` integration <br/>
1. Click `Download`
1. Restart Home Assistant
1. See [Configuration](#configuration) below
## Breaking Change with v3: Entity model and migration notes

<details>
<summary><h3>Manual</h3></summary>
The main places sensor keeps the Display Options state. It now only exposes location-context attributes. Most values that used to be attributes are child sensors under the same places device. For example:
Comment thread
Snuffy2 marked this conversation as resolved.

You probably <u>do not</u> want to do this! Use the HACS method above unless you know what you are doing and have a good reason as to why you are installing manually
* `state_attr('sensor.alice', 'place_name')` becomes `states('sensor.alice_place_name')`
* `state_attr('sensor.alice', 'city')` becomes `states('sensor.alice_city')`
* `state_attr('sensor.alice', 'state')` becomes `states('sensor.alice_state')`
* `state_attr('sensor.alice', 'map_link')` becomes `states('sensor.alice_map_link')`

1. Using the tool of choice open the directory (folder) for your HA configuration (where you find `configuration.yaml`)
1. If you do not have a `custom_components` directory there, you need to create it
1. In the `custom_components` directory create a new folder called `places`
1. Download _all_ the files from the `custom_components/places/` directory in this repository
1. Place the files you downloaded in the new directory you created
1. Restart Home Assistant
1. See [Configuration](#configuration) below
`country` and detailed address/diagnostic sensors are disabled by default. Enable them from the places device page if you use them in automations.

Using your HA configuration directory as a starting point you should now also have this:
```text
custom_components/places/__init__.py
custom_components/places/config_flow.py
custom_components/places/const.py
custom_components/places/manifest.json
custom_components/places/sensor.py
custom_components/places/strings.json
custom_components/places/translations
custom_components/places/translations/en.json
```
</details>
When Extended Attributes is enabled, raw payloads move to `sensor.<name>_extended_data`:

* `state_attr('sensor.alice_extended_data', 'osm_dict')`
* `state_attr('sensor.alice_extended_data', 'osm_details_dict')`
* `state_attr('sensor.alice_extended_data', 'wikidata_dict')`
* `state_attr('sensor.alice_extended_data', 'wikidata_id')`

## Installation via HACS

Ensure that [HACS](https://hacs.xyz/) is installed

<a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=custom-components&repository=places" target="_blank" rel="noreferrer noopener"><img src="https://my.home-assistant.io/badges/hacs_repository.svg" alt="Open your Home Assistant instance to download the places integration." /></a>

Download the `places` integration

Restart Home Assistant

## Configuration
**Configuration is done in the Integrations section of Home Assistant.**
1. [Click Here](https://my.home-assistant.io/redirect/config_flow_start/?domain=places) to directly add a `places` sensor **or**<br/>
  a. In Home Assistant, go to Settings -> [Integrations](https://my.home-assistant.io/redirect/integrations/)<br/>
  b. Click `+ Add Integrations` and select `places`<br/>
1. Add your configuration ([see Configuration Options below](#configuration-options))
1. Click `Submit`
* Repeat as needed to create additional `places` sensors
* Options can be changed for existing `places` sensors in Home Assistant Integrations by selecting `Configure` under the desired `places` sensor.

<a href="https://my.home-assistant.io/redirect/config_flow_start/?domain=places" target="_blank" rel="noreferrer noopener"><img src="https://my.home-assistant.io/badges/config_flow_start.svg" alt="Open your Home Assistant instance to create a places entry." /></a>

[See Configuration Options below](#configuration-options)

Repeat as needed to create additional `places` entries

Options for existing places entries can be changed by clicking the gear icon next to the desired entry under Settings > Devices & services > `places` integration.

## Configuration Options

Expand All @@ -85,13 +77,16 @@ To use, simply enter your advanced options into the `display_options` text area.
__Tip:__ _Build your advanced display options string in a text editor and copy/paste it into display_options field as it is pretty small._

### __Brackets [ ]:__ Fields to show if initial field is blank or empty<br />

These can be nested.

#### Examples

* `name[type]` will show the name, but if name is blank, will show the type instead. If type is also blank, nothing will show for that field
* `name[type[category]]` will show the name, but if name is blank, will show the type instead, but if type is blank, will show the category. If category is also blank, nothing will show for that field.

### __Parenthesis ( ):__ Inclusion/Exclusion Logic to filter the field<br />

#### To include/exclude based on the main field

* __Include:__ Set the first item inside the parenthesis to + to only show the field if it equals one of the states listed
Expand Down Expand Up @@ -127,11 +122,14 @@ These can be nested.
### Brackets and Parenthesis can also be combined

* To recreate `place`:
```

```text
name_no_dupe, category(-, place), type(-, yes), neighborhood, house_number, street
```

* To recreate `formatted_place`:
```

```text
zone_name[driving, name_no_dupe[type(-, unclassified, category(-, highway))[category(-, highway)], house_number, route_number(type(+, motorway, trunk))[street[route_number]], neighborhood(type(house))], city_clean[county], state_abbr]
```

Expand Down Expand Up @@ -167,39 +165,11 @@ __Note:__ `place` and `formatted_place` are not valid fields in the advanced dis
-------
</details>

<details>
<summary>Entity model and migration notes</summary>

The main Places sensor keeps the Display Options state. It only exposes location-context attributes:

* `latitude`
* `longitude`
* `gps_accuracy`
* `entity_picture`
* `attribution`

Most values that used to be attributes are now child sensors under the same Places device. For example:

* `state_attr('sensor.alice', 'place_name')` becomes `states('sensor.alice_place_name')`
* `state_attr('sensor.alice', 'city')` becomes `states('sensor.alice_city')`
* `state_attr('sensor.alice', 'state')` becomes `states('sensor.alice_state')`
* `state_attr('sensor.alice', 'map_link')` becomes `states('sensor.alice_map_link')`

The integration no longer creates a `formatted_address` child sensor.

`country` and detailed address/diagnostic sensors are disabled by default. Enable them from the Places device page if you use them in automations.

When Extended Attributes is enabled, raw payloads move to `sensor.<name>_extended_data`:

* `state_attr('sensor.alice_extended_data', 'osm_dict')`
* `state_attr('sensor.alice_extended_data', 'osm_details_dict')`
* `state_attr('sensor.alice_extended_data', 'wikidata_dict')`
</details>

<details>
<summary>Sample generic `automations.yaml` snippet to send an iOS notify on any device state change</summary>

(the only difference is the second one uses a condition to only trigger for a specific user)

```yaml
- alias: ReverseLocateEveryone
initial_state: 'on'
Expand Down Expand Up @@ -242,16 +212,19 @@ When Extended Attributes is enabled, raw payloads move to `sensor.<name>_extende
url: '{{ trigger.event.data.map_link }}'
hide_thumbnail: false
```

</details>

## Notes

* This component is only useful to those who have device tracking enabled via a mechanism that provides latitude and longitude coordinates (such as the [Home Assistant Mobile App](https://www.home-assistant.io/integrations/mobile_app/), [OwnTracks](https://www.home-assistant.io/integrations/owntracks/), or [iCloud3](https://github.com/gcobb321/icloud3)).
* The OpenStreetMap database is very flexible with regards to tag_names in their database schema. If you come across a set of coordinates that do not parse properly, you can enable debug logging (see below) to see the actual JSON that is returned from the query.
* The OpenStreetMap API requests that you include your valid e-mail address in each API call if you are making a large numbers of requests. They say that this information will be kept confidential and only used to contact you in the event of a problem, see their Usage Policy for more details.
* The map link that gets generated for Google, Apple or OpenStreetMaps has a push pin marking the users location. Note that when opening the Apple link on a non-Apple device, it will open in Google Maps.
* When no `language` value is given, default language will be in the location's local language. When a comma separated list of languages is provided - the component will attempt to fill each address field in desired languages by order.
* When no `language` value is given, default language will be in the location's local language. When a comma-separated list of languages is provided - the component will attempt to fill each address field in desired languages by order.
* Translations are partial in OpenStreetMap database. For each field, if a translation is missing in first requested language it will be resolved with a language following in the provided list, defaulting to local language if no matching translations were found for the list.
* To enable debug logging for this component, add the following to your `configuration.yaml` file

```yaml
logger:
  default: warning
Expand All @@ -269,13 +242,16 @@ python -m pip install --group dev -e .
```

## Prior Contributions:

* Previous Authors: [Jim Thompson](https://github.com/tenly2000) & [Ian Richardson](https://github.com/iantrich)
* Current Author: [Snuffy2](https://github.com/Snuffy2)

## Contributions are welcome!

If you want to contribute to this please read the [Contribution guidelines](CONTRIBUTING.md)
***

[integration-usage-shield]: https://img.shields.io/badge/dynamic/json?color=41BDF5&logo=home-assistant&label=integration%20usage&suffix=%20installs&cacheSeconds=15600&url=https%3A%2F%2Fanalytics.home-assistant.io%2Fcustom_integrations.json&query=%24.places.total&style=for-the-badge
[downloads-shield]: https://img.shields.io/github/downloads/custom-components/places/total?style=for-the-badge&label=total%20downloads
[downloads-latest-shield]: https://img.shields.io/github/downloads-pre/custom-components/places/latest/total?style=for-the-badge
[releases]: https://github.com/custom-components/places/releases
Expand All @@ -286,7 +262,5 @@ If you want to contribute to this please read the [Contribution guidelines](CONT
[license-shield]: https://img.shields.io/github/license/custom-components/places?color=blue&style=for-the-badge
[hacsbadge]: https://img.shields.io/badge/HACS-Default-blue.svg?style=for-the-badge
[hacs]: https://hacs.xyz
[community-forum-shield]: https://img.shields.io/badge/community-forum-orange.svg?label=HA%20Community&style=for-the-badge
[community-forum]: https://community.home-assistant.io/t/reverse-geocode-sensor-places-using-openstreetmap-custom-component
[coverage]: https://htmlpreview.github.io/?https://github.com/custom-components/places/blob/python-coverage-comment-action-data/htmlcov/index.html
[coverage-shield]: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fcustom-components%2Fplaces%2Fpython-coverage-comment-action-data%2Fendpoint.json&style=for-the-badge
Loading