Skip to content
Component to integrate with OpenStreetMap Reverse Geocode (PLACE)
Branch: master
Clone or download
iantrich Merge pull request #14 from Xaldimo/pr/1
Correct GPS deviation implementation
Latest commit 2325f23 Nov 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
custom_components/places Update Nov 19, 2019 Create Jul 26, 2019
LICENSE Add files via upload Jun 16, 2019 Updated "Configuration Options" section Oct 9, 2019 Create Jul 26, 2019


GitHub Release GitHub Activity License


Discord Community Forum

Component to integrate with OpenStreetMap Reverse Geocode (PLACE)


  1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
  2. If you do not have a custom_components directory (folder) there, you need to create it.
  3. In the custom_components directory (folder) create a new folder called places.
  4. Download all the files from the custom_components/places/ directory (folder) in this repository.
  5. Place the files you downloaded in the new directory (folder) you created.
  6. Add your configuration
  7. Restart Home Assistant

Using your HA configuration directory (folder) as a starting point you should now also have this:


Example configuration.yaml

sensor places_jim:
  - platform: places
    name: jim
    devicetracker_id: device_tracker.jim_iphone8
    options: zone,place
    map_provider: google
    map_zoom: 19
    home_zone: zone.jim_home
    api_key: !secret email_jim

sensor places_sharon:
  - platform: places
    name: sharon
    devicetracker_id: device_tracker.sharon_iphone7
    options: zone, place
    map_provider: apple
    map_zoom: 18
    home_zone: zone.sharon_home
    api_key: !secret email_sharon

sensor places_aidan:
  - platform: places
    name: aidan
    devicetracker_id: device_tracker.aidan_iphone7plus
    options: place
    map_provider: google
    map_zoom: 17
    home_zone: zone.aidan_home
    api_key: !secret email_aidan

Configuration options

Key Type Required Description Default
platform string True places None
devicetracker_id string True entity_id of the device you wish to track None
name string False Friendly name of the sensor places
home_zone string False Calculates distance from home and direction of travel if set zone.home
api_key string False OpenStreetMap API key (your email address). no key
map_provider string False google or apple apple
map_zoom number False Level of zoom for the generated map link <1-20> 18
options string False Display options: zone, place, street_number, street, city, county, state, postal_code, country, formatted_address zone, place

Sample attributes that can be used in notifications, alerts, automations, etc:

  "formatted_address": "Richmond Hill GO Station, 6, Newkirk Road, Beverley Acres, Richmond Hill, York Region, Ontario, L4C 1B3, Canada",
  "friendly_name": "sharon",
  "postal_town": "-",
  "current_latitude": "43.874149009154095",
  "distance_from_home_km": "7.24 km",
  "country": "Canada",
  "postal_code": "L4C 1B3",
  "direction_of_travel": "towards home",
  "neighbourhood": "Beverley Acres",
  "entity_picture": "/local/sharon.png",
  "street_number": "6",
  "devicetracker_entityid": "device_tracker.sharon_iphone7",
  "home_longitude": "-79.7323453871",
  "devicetracker_zone": "not_home",
  "distance_from_home_m": 17239.053,
  "home_latitude": "43.983234888",
  "previous_location": "43.86684124904056,-79.4253896502715",
  "previous_longitude": "-79.4253896502715",
  "place_category": "building",
  "map_link": ",-79.42642783709209&z=18",
  "last_changed": "2018-05-02 13:44:51.019837",
  "state_province": "Ontario",
  "county": "York Region",
  "current_longitude": "-79.42642783709209",
  "current_location": "43.874149009154095,-79.42642783709209",
  "place_type": "building",
  "previous_latitude": "43.86684124904056",
  "place_name": "Richmond Hill GO Station",
  "street": "Newkirk Road",
  "city": "Richmond Hill",
  "home_zone": "zone.sharon_home"

Sample generic automations.yaml snippet to send an iOS notify on any device state change: (the only difference is the second one uses a condition to only trigger for a specific user)

- alias: ReverseLocateEveryone
  initial_state: 'on'
    platform: event
    event_type: places_state_update
  - service: notify.ios_jim_iphone8
      title: 'ReverseLocate: {{ }} ({{ }}) {{ }}'
      message: |-
        {{ }} ({{ }}) 
        {{ }}
        {{ }} from home and traveling {{ }}
        {{ }} ({{ }})
          url: '{{ }}'
          hide_thumbnail: false

- alias: ReverseLocateAidan
  initial_state: 'on'
    platform: event
    event_type: places_state_update
    condition: template
    value_template: '{{ == "aidan" }}'
  - service: notify.ios_jim_iphone8
      title: 'ReverseLocate: {{ }} ({{ }}) {{ }}'
      message: |-
        {{ }} ({{ }}) 
        {{ }}
        {{ }} from home and traveling {{ }}
        {{ }} ({{ }})
          url: '{{ }}'
          hide_thumbnail: false


  • This component is only useful to those who have device tracking enabled via a mechanism that provides latitude and longitude co-ordinates (such as Owntracks or iCloud).
  • The OpenStreetMap database is very flexible with regards to tag_names in their database schema. If you come across a set of co-ordinates that do not parse properly, you can enable debug messages 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 maps has a push pin marking the users location.
  • The map link for Apple maps is centered on the users location - but without any marker.
  • To enable detailed logging for this component, add the following to your configuration.yaml file
    default: warn
      custom_components.sensor.places: debug  

Original Author: Jim Thompson

Contributions are welcome!

If you want to contribute to this please read the Contribution guidelines

You can’t perform that action at this time.