Proposal Open Location Code

From OpenStreetMap Wiki
Jump to navigation Jump to search

Proposal: Non-technical overview

With reference to https://github.com/openstreetmap/openstreetmap-website/issues/1807 and https://github.com/openstreetmap/openstreetmap-website/pull/1818 this is a proposal for OLC (plus code, https://github.com/google/open-location-code) support in a number of areas.

Part 1: Enable look up of location via long OLC.

Part 2: Enable lookup of location via short OLC (see technical proposal below)

Part 3: Enabling the lookup of plus codes within OLC, include any or all of the following:

  • the OpenStreetMap "where's this" (located in the search box)
    • Example, when near 1.286812,103.854438, clicking "where's this" should also return 6PH57VP3+PQ in the sidebar.
  • a search for 1.286812,103.854438 could return "results from OLC" among the list of results.
  • "show address"

Technical Proposal

The technical implementation is of course left to developers (https://github.com/openstreetmap/openstreetmap-website/pull/1818). Conceptually, an implementation would detect plus codes (entered into the search box) based on

  • the pluscode alphabet, "23456789CFGHJMPQRVWX", and
  • the plus sign, "+",

For patterns that produce

  • global codes , such as "796RWF8Q+WF", and
  • local codes, such as "WF8Q+WF"
  • local codes with locality, such as "WF8Q+WF Praia, Cape Verde".

For the process how these are handled, see github/google/open-location-code/wiki/Supporting-OLC-in-your-app

Notes:

  • This proposal leaves it open whether only long codes are implemented, or also short codes.
  • If short codes will be implemented:
    • a search for "WF8Q+WF Praia, Cape Verde" would need to resolve "Praia, Cape Verde" (offering nominatim alternatives to the user), and then resolving the short code;
    • also, a search when zoomed in, should jump to the nearest "WF8Q+WF".
  • If short codes will not be implemented, then the search engine should warn "local Open Location Codes are ignored."

NOTE: there are a new proposal to implement it as a subtype, see git/openstreetmap-website/issues/2104. -> issue has been closed / rejected.

Comments on the proposal in relation to trial deployment

There's now a way to test this:

Note that this currently only supports global codes and doesn't support "where's this". (Question: I presume this is based on https://github.com/openstreetmap/openstreetmap-website/pull/1818 by jguthrie? Bjohas (talk) 11:27, 12 January 2019 (UTC))

No, TomH's implementation was written about 7 days earlier. jguthrie's implementation was dropped altogether, as it didn't add any new features at all. Mmd (talk) 11:39, 12 January 2019 (UTC)

where's this

The OpenStreetMap "where's this" (located in the search box) is not in scope of TomH's implementation for the osm.org site.

Global codes

Only global codes are in scope of TomH's implementation for the osm.org site.

Only global codes are currently in scope for osm.org, all references and examples on this page using some local codes should be removed at this time.

@Mmd: I am grateful for any implementation of OLC, so thank you for suggesting that global codes may be in scope. However, it is important that this is a proposal. I.e., at this stage, this is a proposal to the OSM community, aimed at finding some consensus within the community. So what are the reasons for local codes being in or out of scope? Would it be possible to discuss this on the talk page? Thanks! Bjohas (talk) 00:31, 12 January 2019 (UTC)
My comment was only referring to the implementation by TomH which is now deployed on https://tomh.apis.dev.openstreetmap.org/ - it wasn't meant to imply any kind of decision for osm.org, which is still to be made. Mmd (talk) 09:42, 12 January 2019 (UTC)
Many thanks for clarifying, much appreciated! - that's what I thought. I'm moving the above comment into this section too! Thanks again! Bjohas (talk) 11:22, 12 January 2019 (UTC)

Rationale

What is OLC (plus codes)?

From https://github.com/google/open-location-code:

  • Open Location Code is a technology that gives a way of encoding location into a form that is easier to use than latitude and longitude. The codes generated are called plus codes, as their distinguishing attribute is that they include a "+" character.
  • The technology is designed to produce codes that can be used as a replacement for street addresses, especially in places where buildings aren't numbered or streets aren't named.
  • Plus codes represent an area, not a point. As digits are added to a code, the area shrinks, so a long code is more precise than a short code.
  • Codes that are similar are located closer together than codes that are different.
  • A location can be converted into a code, and a code can be converted back to a location completely offline.
  • There are no data tables to lookup or online services required. The algorithm is publicly available and can be used without restriction.

The code on the github repository, which includes all specifications necessary to generate/decode plus codes, is licensed under the Apache Licence 2.0 (https://github.com/google/open-location-code/blob/master/LICENSE).

This page presents the rationale for OLC: https://github.com/google/open-location-code/wiki/Evaluation-of-Location-Encoding-Systems. It puts forward why (in the opinion of the creator) OLC has desirable features that are not met by other code types.

Advantages of OLC over other location codes

This text has now been moved back here from the talk page. Please edit this text, but before deleting it, please contribute to discussion on the talk page first: Talk:Proposal_Open_Location_Code#Advantages. Bjohas (talk) 20:43, 11 January 2019 (UTC)

An advantage of OLC (that is shared with many other codes)is that codes should be short enough that they can be memorised. The following advantages (taken from https://github.com/google/open-location-code/wiki/Evaluation-of-Location-Encoding-Systems) are more specific to OLC, although some features are shared by other codes as well:

  • A plus code is sufficient on its own, and does not require any additional information such as country name
  • Each place has only one plus code.
  • Plus codes do not include easily confused characters (e.g., 0 and O, 8 and B etc)
  • Plus codes do not include profanity, or preferably, any words in any language (this was subject to extensive multi-language testing)
  • With plus codes you can look at two codes and tell if they are close together and even the direction. This helps people find their way and makes the plus codes more usable;
  • Plus codes represent an area, not a point; the size of the area described by a plus code variable
  • Shortening a plus code represents a larger area that contains the original location. A side effect of this is that nearby codes have a common prefix;
  • The plus code for a place is deterministically generated (with a simple algorithm) and does not require any setup or application
  • Plus codes can be generated and decoded offline. (This is important because mobile data networks may not be ubiquitous or cheap)
  • Plus codes do not depend on any one provider so that there is no risk that they will stop working if one company goes out of business
  • The algorithm for plus codes is published publicly and be free to use.
  • They are easily recognized by the "+" character and thus unlikely to be confused with place names / ZIP codes / other geohash schemes.

Note: These advantages are not generic to all possible location codes; OLC was specifically designed to meet all of these. Other codes only meet that list partially. It is, of course, a matter of opinion whether all of these are important. However, OLC is the only location code that meet all of these requirements. See https://github.com/google/open-location-code/wiki/Evaluation-of-Location-Encoding-Systems for a comparison with other types of codes.

Disadvantages of OLC (as a code)

  • Although OLC has been carefully designed to not match with any real words, it could be conceived that at some point a name is interpreted incorrectly. However, as the search function always provides several options and a name match would arguably receive priority, this wouldn't really provide any problem.
  • If you can't read latin characters, plus codes are obviously a poor choice (added by @Mmd:, moved here by Bjohas (talk)). Please see discussion on Talk:Proposal_Open_Location_Code#If_you_can.27t_read_latin_characters.2C_plus_codes_are_obviously_a_poor_choice.. This issue was a concern in the development of OLC, but turned out to be fine. Bjohas (talk) 11:50, 12 January 2019 (UTC)

Advantages of OLC to OSM users: How and to which OSM users/maintainers could this proposal be helpful?

Background. OSM is used in many situations where mapping and other local GIS resources are limited or not at all available; for example, this includes humanitarian and international development work. It should be noted that unlawful use of OSM includes "Operate dangerous businesses such as emergency services or air traffic control, where the use or failure of the Services could lead to death, personal injury or significant property damage" ([2]]), and the "humanitarian/international development work" excludes such "first responder" services. Instead, OSM can be used for planning vaccination campaigns or school sites.

Open Location Code. The goals that OLC specifically tries to solve agree with this common use case of OSM, it adds a way to communicate your findings on OSM to people somewhere on the ground and vice versa, communicate a location e.g. over the phone and easily look up what is known about that region etc.

In other words, having mapped an area, how can the location of a place be communicated? Remote mapping gives you the buildings (and roads), and it's easy to spot features such as villages. However, the names of those villages are not easy to obtain, and may well be unknown to local (e.g. health) workers. Open Location Code / Plus codes allow the communication of a village, without using the usual lat/lon coordinate systems (see below why OLC / plus codes have an advantage over lat/lon). When all other information on the map fails to be helpful, the OLC is always guaranteed to be there.

This page https://wiki.osmfoundation.org/wiki/Mission_Statement states these two things:

  1. We want OSM data to be used as widely as possible.
  2. OSM wants you to map the things you care about and will ensure that you have the freedom to do so. This safeguards the accessibility of our map to diverse users with differing needs.

In light of this, it is worth noting that:

  • Regarding 1, for some projects, OSM data will be used more if users can locate OSM data via plus codes.
  • Regarding 2, some of those projects working on education and school infrastructure in low-income countries (which are usually poorly mapped by commercial maps) will find this beneficial. Such projects care about people having 'postcodes' that describes such infrastructure in contexts where road names and addresses often are not generally available.
    • It could for that be argued that we would like OSM to allow us to map those (which OSM already does), but also:
    • recognising such projects as being run by "diverse users with diverse needs", one of which includes the need to use (an open source algorithm, i.e. OLC) to locate objects in OSM, and to do so with a scheme that people find easy to use (e.g. shortcodes).
  • "Applicable projects" include e.g.
    • HOTOSM
    • Ghanaian educators http://bjohas.de/go/atlas2017
    • Supporting health worker in Central Province, Zambia (e.g. in Fiwila).
    • The use of plus codes in Cabo Verde.

Additional points.

  • Further added bonus can be the use of OLC for disambiguation when talking about edits for places with very similar names, although this is arguably a much smaller use case.
  • Another nice thing that can be provided by OLC support is short links to specific map overviews for quick map data sharing, although this is not necessarily a goal of this proposal.

Disadvantages: How and to which OSM users/maintainers could this proposal be harmful?

  • The implementation of OLC could possibly create a snowball effect for other systems wanting to be added. There are no clear rules about what and how many systems would be eligible.
  • Every additional system added in this way increases the complexity of the code for maintainers and developers. It's not something where a pull request is written once and committed and never causes work again. Every system added increased the technical debt.
  • If every system added in this way boldly requests "discoverability" (see next section), then the user interface suffers; someone entering a search term could potentially bombarded with a lot of "results from XYZ addressing system" replies they didn't ask for, and someone asking "where is this" would likewise receive a lot of potentially confusing replies in various addressing systems.

Important considerations for implementation: incomplete implementation may be harmful

  • Poor discoverability of the feature. How should a user know that the search box support plus codes?
  • Poor user experience, if a user tries to enter a local code, and won't see a result
    • @Mmd: notes that currently short codes are not supported
  • Poor user experience, if a user enters an invalid plus global code with a typo (e.g. "6PH57VP3+XB") and won't get any result at all, not even an error message.

@Mmd:: I have put this into a sub-section to do with implementation - I agree that "incomplete implementation may be harmful". Hope this is ok. I'm moving the bit about latin character up to disadvantages of OLC as such, as it doesn't just concern OSM. Bjohas (talk) 11:41, 12 January 2019 (UTC)

Yes, that's ok. There's a number of potential implementation specific issues here which need to be evaluated in a bit more detail. Mmd (talk) 11:45, 12 January 2019 (UTC)
  • Local codes support: interoperability issues between officially generated plus.codes and a possible "home grown" version with completely unclear side effects. osm.org would never use the same service to determine local codes as Google does. A custom local code implementation would have to make sure that names are unique, and even then it's not clear that Google might use the same name in a different context, rendering the generated local code pretty much useless. For further discussion see: https://github.com/google/open-location-code/issues/126#issuecomment-349689793

What this proposal is not

Note that this proposal is not about adding OLC (plus codes) to OSM data as an 'OLC' tag. For the avoidance of doubt, this is not about adding e.g. "pluscode=6PH57VP3+PQ" to OSM objects, as such a code would be redundant. Rather, the proposal is about OLC support within the search / what's there interface.

Contributors to this proposal

The page contributors are available via "view history". I would nevertheless propose that those who contribute significantly to this page (and have a stake in the matter) add their name to this proposal. You may also want to 'watch' this page, to be emailed updates.

"OSM is powered by its Community. Engage positively with the Community, be a good and respectful neighbour and assume good intent." https://wiki.osmfoundation.org/wiki/Mission_Statement

FAQ and clearing up common misunderstandings

(The section is based on contents first put on the Discussion page, as it clearly contributes in the proposal itself. Note that while those sections were written by Bjohas (talk), they reflect discussion on the above github pages, but without actually quoting from github.)

Is OLC proprietary?

No, OLC is fully free

Although OLC was created by a (then and current) Google employee and recently got support on Google Maps, Google implemented strong guarantees for full free usage through Apache licensing of related source code (APL is comparable to e.g. MIT and BSD licenses, but adds protection against any possible litigation over patents that might ever be involved from Google's side and all other contributors). Also the OLC algorithm itself is rather trivial and comes with a blank permission to be used for anything at all, and (unlike other Google products) the code doesn't have Google branding (it's not the 'Google location code'). Other projects related to OSM already use it: OSMAnd and Maps.Me support OLC. Response added by Bjohas (talk) 22:26, 4 January 2019 (UTC), edited for clarity by LaPingvino (talk) 23:37, 4 January 2019 (UTC); Maps.Me support checked, support has been added for 8 digits codes: "6GVV2FXH+": Bjohas (talk) 11:37, 12 January 2019 (UTC)

Are short codes proprietary?

No, the reference point is used with a simple algorithm and falls back on the rest of name resolution

A question raised on github was whether short codes are proprietary, because essentially somebody has to chose the reference point. Shortening codes is described here https://github.com/google/open-location-code/wiki/Guidance-for-shortening-codes and users can chose their own reference point.

For example, 6889CW6G+6X can be shortened as:

  • CW6G+6X, Quatro Bocas sandwich shop, Altamira, Brazil
  • CW6G+6X, Belo Sun Mining, Altamira, Brazil
  • CW6G+6X, Pousada Mangueira, Altamira, Brazil

Note that these three locations do not all fall within "6889". So, if the community reference point is Belo Sun Mining, I choose my address to be "CW6G+6X, Belo Sun Mining, Altamira, Brazil".

Of course, POIs used in these short codes depends on what e.g. Google or OSM have available in the system. When picking a short code, care should be taken that the lookup system can possibly have this reference point available.

Also short codes can be used without a reference point, which basically means resolving them with the current open location of the map as reference point.

Note: This does not require the OSM website to resolve the short code - given the long code of the POI (from the OSM website) and the short code of the location, the long code for the location can be generated (outside the OSM website).

Would a resolver do the trick?

Q: What you had another website, e.g. "https://olctoosm.org", so that https://olctoosm.org/6889CW6G+6X resolves to lat/lon and then to OSM?

A: Bjohas. My view on this is that it's technically simple, but from a UI perspective not desirable. Non-technologically literate persons would find this hard to use. I've spent hours troubleshooting on the phone with users in low-income countries, where much of the discussion is around which button to press, what to do next, to interpret error messages. Power and connectivity fails regularly. Having a separate website as the main way to resolve OLC to OSM is therefore not workable for the users I have in mind. Moreover, the main proposal suggests the OLC to be shown under "what's here", so that it becomes a two-way process Bjohas (talk) 22:20, 4 January 2019 (UTC)

Should other open schemes be implemented?

Q: Should other open schemes be implemented?

A: Bjohas. From my perspective, I have no problem with that. I have advocated for OLC/plus codes because of the advantage stated on this proposal page. For example, Geohash (base32) creates shorter codes, than OLC (base20); however, the 20 symbols for OLC were chosen carefully to avoid confusions between characters, and so that no offensive words are generated. So it's not only about the shortest code, but about a code that's very usable to a broad range of users who may not be not technology-literate, but do have a need to communicate their location. But yes, if the OSM community would like to implement other codes, that's fine by me! Bjohas (talk) 22:21, 4 January 2019 (UTC)

Try it out

Thanks to https://github.com/tomhughes, there's now a way to test this:

Note that this currently only supports global codes.

Interesting Links

Change log

  • I have restructured the proposal into three parts, so that people can comment on various parts. Part 1 would appear to be less contentious than Parts 2 and 3. Bjohas (talk) 14:53, 12 January 2019 (UTC)
Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=Proposal_Open_Location_Code&oldid=2506790"