Skip to content

Commit 31a5053

Browse files
drinckesdrinckes
authored
Move wiki pages into Documentation (#590)
* Move external implementation list to repo * Add naming guidelines from wiki * Add FAQ from the wiki, format to one sentence per line. * Move field collection practices from wiki (and format to one sentence per line). * Move Wiki content to Reference * Move plus.codes API from wiki (and format to one sentence per line). * Move GIS info from wiki (and format) * Move app page from wiki (and format) * Move spreadsheet page from wiki (and format) * Move who uses olc from wiki and format * Add Documentation/README * Move short code guidance from wiki and format
1 parent 73abcd7 commit 31a5053

11 files changed

+791
-0
lines changed

‎Documentation/External_Implementations.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# External Implementations
2+
3+
This page lists implementations of the Open Location Code library by third parties.
4+
These include implementations in languages other than the those in this repository.
5+
6+
These implementations have not been tested or reviewed, and are included here as a convenience.
7+
8+
| Language | Link | Notes |
9+
| ------------------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
10+
| Ada | https://github.com/malaise/ada/ | |
11+
| C# (.NET standard) | https://github.com/JonMcPherson/open-location-code | |
12+
| Common Lisp | https://github.com/ralph-schleicher/open-location-code | |
13+
| EMACS | https://gitlab.liu.se/davby02/olc | |
14+
| R | https://github.com/Ironholds/olctools | |
15+
| Solidity | https://etherscan.io/address/0xf85c6320cc60dec45af1f7ce82b13dd24d539690#code#F3#L28 | URL is a link to a contract, not a repo |
16+
| Swift 3.x, 4.x | https://github.com/curbmap/OpenLocationCode-swift | Not fully implemented |
17+
| Swift 5.0 | https://github.com/google/open-location-code-swift | This library supports Objective-C for iOS, macOS, tvOS, and watchOS. |
18+
| Typescript | https://github.com/tspoke/typescript-open-location-code | |

‎Documentation/FAQ.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Open Location Code Frequently Asked Questions
2+
3+
## Table Of Contents
4+
- [Open Location Code Frequently Asked Questions](#open-location-code-frequently-asked-questions)
5+
- [Table Of Contents](#table-of-contents)
6+
- [Background](#background)
7+
- ["plus codes" or "Open Location Code"?](#plus-codes-or-open-location-code)
8+
- [What are they for?](#what-are-they-for)
9+
- [Why not use street addresses?](#why-not-use-street-addresses)
10+
- [Why not use latitude and longitude?](#why-not-use-latitude-and-longitude)
11+
- [Why is Open Location Code based on latin characters?](#why-is-open-location-code-based-on-latin-characters)
12+
- [Plus code digital addresses](#plus-code-digital-addresses)
13+
- [Reference location dataset](#reference-location-dataset)
14+
- [Plus code addresses in Google Maps](#plus-code-addresses-in-google-maps)
15+
- [Plus code addresses of high-rise buildings](#plus-code-addresses-of-high-rise-buildings)
16+
- [Plus code precision](#plus-code-precision)
17+
18+
19+
20+
## Background
21+
22+
### "plus codes" or "Open Location Code"?
23+
24+
The software library (and this GitHub project) is called "Open Location Code", because it's a location code that is open source.
25+
The codes it generates are called "plus codes" because they have a plus sign in them.
26+
27+
### What are they for?
28+
29+
Plus codes provide a short reference to any location.
30+
We created them to provide a way to refer to any location, regardless of whether there are named roads, unnamed roads, or no roads at all.
31+
32+
### Why not use street addresses?
33+
34+
A lot of rural areas can be far away from roads, and people still want to be able to refer to specific locations.
35+
Also, at lot of the roads in the world don't have names, and so locations along those roads don't have addresses.
36+
There is an estimate by the World Bank that the majority of urban roads don't have names.
37+
38+
Street-based addressing projects are expensive and slow, and haven't made much of a dent in this problem.
39+
Plus codes can be assigned rapidly and because they can be used immediately can solve the addressing problem quickly and cheaply.
40+
41+
### Why not use latitude and longitude?
42+
43+
One answer is that if latitude and longitude were a practical solution, people would already be using them.
44+
The problem with latitude and longitude is that they are two numbers, possibly signed, with a lot of digits, and the order is important.
45+
46+
But latitude and longitude, and many other systems such as MGRS, geocodes, etc, also have the problem that they do not look like addresses.
47+
We all know what an address looks like - a collection of references from less detailed to more detailed, typically: country, state, city, street, and house.
48+
This hierarchy is important since it makes it easy to determine if something is near or far without having to understand the whole thing.
49+
You can tell if it's in a different city without having to know the street name.
50+
51+
### Why is Open Location Code based on latin characters?
52+
53+
We are aware that many of the countries where Open Location Codes will be most useful use non-Latin character sets, such as Arabic, Chinese, Cyrillic, Thai, Vietnamese, etc.
54+
We selected Latin characters as the most common second-choice character set in these locations.
55+
We considered defining alternative Open Location Code alphabets in each character set, but this would result in codes that would be unusable to visitors to that region, or internationally.
56+
57+
## Plus code digital addresses
58+
59+
Plus code digital addresses use known address information, like country, state, city, and then use the plus code to provide the final information.
60+
Typically converting a plus code to a plus code address removes the first four digits from the code to shorten it to just six digits.
61+
62+
Any city or place name within approximately 30-50 km can be used to recover the original location.
63+
64+
### Reference location dataset
65+
66+
The open source libraries support conversion to/from addresses using the latlng of the reference location.
67+
Callers will need to convert place names to/from latlng using a geocoding system.
68+
69+
Providing a global dataset isn't within scope of this project.
70+
For a potential free alternative, see [Open Street Map](https://wiki.openstreetmap.org/) and derived geocoding service [Nominatim](https://nominatim.org/).
71+
72+
### Plus code addresses in Google Maps
73+
74+
Google Maps displays plus code addresses on all entries.
75+
It does this by using the location of the business for the plus code, and then using the place name to shorten the plus code to a more convenient form.
76+
77+
If the listing is managed by the business owner, it will try to use a place name from the address, otherwise it will use Google's best guess for the place name. (Google tries to pick names for cities rather than suburbs or neighbourhoods.)
78+
79+
If you think a different place name would be better, you can use that, and as long as Google knows about that place name the plus code address should work.
80+
81+
### Plus code addresses of high-rise buildings
82+
83+
Plus codes don't include the floor or apartment in high-rise buildings.
84+
If you live in a multi-storey building located at "9G8F+6W, Zürich, Switzerland", think of the plus code as like the street name and number, and put your floor or apartment number in front: "Fourth floor, 9G8F+6W, Zürich, Switzerland"
85+
86+
The reason for this is that plus codes need to be created without knowing specifically what is there.
87+
The other reason is that addresses in high-rise buildings are assigned differently in different parts of the world, and we don't need to change that.
88+
89+
### Plus code precision
90+
91+
The precision of a plus code is indicated by the number of digits after the "+" sign.
92+
93+
* Two digits after the plus sign is an area roughly 13.7 by 13.7 meters;
94+
* Three digits after the plus sign is an area roughly 2.7 by 3.5 meters;
95+
* Four digits after the plus sign is an area roughly 0.5 by 0.8 meters.
96+
97+
Apps can choose the level of precision they display, but should bear in mind the likely precision of GPS devices like smartphones, and the increased difficulty of remembering longer codes.
98+
99+
One reason to use three or four digits after the plus sign might be when addressing areas that contain small dwellings, to avoid having multiple dwellings with the same plus code address.
100+

‎Documentation/README.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Documentation
2+
3+
The wiki is where you can find out information about using the software, the codes, or the API.
4+
5+
### Common pages
6+
7+
* [External Implementations](External_Implementations.md) - need an Ada or Typescript library?
8+
* [Frequently Asked Questions (FAQ)](FAQ.md)
9+
* [Who is using Plus Codes?](Reference/Plus_Code_Users.md)
10+
11+
### Specification and technical implementation
12+
13+
* [Open Location Code Overview](Specification/olc_definition.adoc)
14+
* [Open Location Code Specification](Specification/specification.md)
15+
* [Guidance for Shortening Codes](Specification/Short_Code_Guidance.md)
16+
* [Open Location Code Reference API](Specification/API.md)
17+
* [Plus Codes and Open Location Code Naming Guidelines](Specification/Naming_Guidelines.md)
18+
19+
### Technical
20+
21+
* [An Evaluation of Location Encoding Systems](Reference/comparison.adoc)
22+
* [Supporting plus codes in GIS software](Reference/GIS_Software.md)
23+
* [Supporting plus codes in an app](Reference/App_Developers.md)
24+
25+
### Tools
26+
27+
* [Field Data Collection Practices](Reference/Field_Collection_Data_Practices.md)
28+
* [https://plus.codes API Reference](Reference/plus.codes_Website_API.md)
29+
* [Using Plus Codes in Spreadsheets](Reference/Using_Spreadsheets.md)

‎Documentation/Reference/App_Developers.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Supporting plus codes technology in apps and sites
2+
3+
This page gives guidelines for how to support plus codes in a website or mapping application.
4+
These guidelines should make it clear that adding support for OLC is not onerous, but actually quite easy.
5+
6+
> Note that with the availability of the [plus codes API](https://github.com/google/open-location-code/wiki/Plus-code-API), these instructions really only apply to apps that require offline support.
7+
If your app or site can rely on a network connection, integrating with the API will give a better solution.
8+
9+
# Supporting plus codes for search
10+
11+
To support plus codes for searching, there are three different cases:
12+
* global codes, such as "796RWF8Q+WF"
13+
* local codes, such as "WF8Q+WF"
14+
* local codes with a locality, such as "WF8Q+WF Praia, Cabo Verde"
15+
16+
The assumption is that this is being done by a mapping application, that allows people to enter queries and then highlights that location on a map or uses it for directions.
17+
18+
## Supporting global codes
19+
20+
Global codes can be recognised and extracted from a query using a regular expression:
21+
22+
```
23+
/(^|\s)([23456789C][23456789CFGHJMPQRV][23456789CFGHJMPQRVWX]{6}\+[23456789CFGHJMPQRVWX]{2,7})(\s|$)/?i
24+
```
25+
26+
This will extract (in capturing group **2**) a global code at the start or end of a string, or enclosed with spaces.
27+
It will not match a global code embedded in a string such as "777796RWF8Q+WFFFFFFF".
28+
29+
If a location query includes a global code, the rest of the query can be ignored, since the global code gives the latitude and longitude.
30+
31+
To support a global code, once you have the user query, match it against the above regex, and if you have a match use the `decode()` method to get the coordinates, and use the center latitude and longitude.
32+
33+
## Supporting local codes
34+
35+
A variant of the global code regex can be used to check whether a location query includes a local code:
36+
37+
```
38+
/(^|\s)([23456789CFGHJMPQRVWX]{4,6}\+[23456789CFGHJMPQRVWX]{2,3})(\s|$)/?i
39+
```
40+
41+
If the query matches, *and the user has not entered any other text*, then another location must be used to recover the original code.
42+
If you are displaying a map to the user, then use the current map center, pass it to the `recoverNearest()` method to get a global code, and then decode it as above.
43+
44+
If there is no map, you can use the device location.
45+
If you have no map and cannot determine the device location, a local code is not sufficient and you should display a message back to the user asking them to provide a town or city name or the full global code.
46+
47+
## Supporting local codes with localities
48+
49+
If the user input includes a local code with some other text, then extract the local code and send the remaining text to your geocoding service (Nominatim, Google, etc).
50+
Use the location returned by your geocoding service as the reference location in the `recoverNearest()` method to get a global code, decode that and you have the location.
51+
52+
## Displaying the result
53+
54+
If the user specified a plus code in their query, the result should match.
55+
That is, it is easier to understand if they enter a plus code to get a plus code displayed as the result.
56+
Searching for a plus code and displaying the result back to the user as "14°55'02.3"N 23°30'40.7"W" is confusing, unhelpful and should be avoided.
57+
58+
# Computing plus codes for places
59+
60+
Superficially computing plus codes for places is trivial.
61+
All that is needed is to call the `encode()` method on the coordinates, and then to display the code.
62+
63+
The problem is that this only displays the global code, not the more convenient and easy to remember local code.
64+
But to display the local code, you need to do two things:
65+
66+
* Compute the locality name
67+
* Ensure that the locality is located near enough
68+
69+
## Computing a locality name
70+
71+
To display a local code (e.g., WF8Q+WF), you need a reference location that is within half a degree latitude and half a degree longitude.
72+
73+
Make a call to a reverse geocoding backend, preferably one that returns structured information, and extract the town or city name.
74+
75+
Some geocoding backends are more suitable than others, so you might need to perform some tests.
76+
77+
## Ensuring the locality is near enough
78+
79+
After reverse geocoding the location and extracting the locality name, you should make a call to a geocoding service to get the location of the locality.
80+
This is likely to be its center, not the position of the plus code, and could be some distance away.
81+
82+
You want it to be as close as possible, because other geocoding services are likely to position it slightly differently.
83+
If it is very close to half a degree away, another geocoding service could result in the plus code being decoded to a different location.
84+
85+
Typically you should aim for a locality within a quarter of a degree - this is approximately 25km away (at the equator) so still quite a large range.
86+
87+
If the locality is near enough, you should display the local code and locality together.
88+
The `shorten()` method in the OLC library may remove 2, 4, 6 or even 8 characters, depending on how close the reference location is.
89+
Although all of these are valid, we recommend only removing the first 4 characters, so that plus codes have a consistent appearance.
90+
91+
# Summary
92+
93+
Supporting plus codes in search use cases should not be a complex exercise.

0 commit comments

Comments
 (0)