diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 49d1ae32..20e3b6c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,7 +46,7 @@ A few things to note: ## Contributing a new implementation -If you have an implementation in your own repository, that's great! Just add a link to it in our [wiki](https://github.com/google/open-location-code/wiki/Other-Implementations). +If you have an implementation in your own repository, that's great! Just add a link to it in our [wiki](https://github.com/google/open-location-code/tree/main/docs/wiki/Other-Implementations.md). Follow this process for contributing a new implementation: diff --git a/README.md b/README.md index 7f7bd971..05a41463 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Links ----- * [Demonstration site](http://plus.codes/) * [Mailing list](https://groups.google.com/forum/#!forum/open-location-code) - * [Comparison of existing location encoding systems](https://github.com/google/open-location-code/wiki/Evaluation-of-Location-Encoding-Systems) + * [Comparison of existing location encoding systems](https://github.com/google/open-location-code/tree/main/docs/wiki/Evaluation-of-Location-Encoding-Systems.md) * [Open Location Code definition](https://github.com/google/open-location-code/blob/master/docs/olc_definition.adoc) Description @@ -74,7 +74,7 @@ Rather than a large city size feature to generate the reference location, it is better to use smaller, neighbourhood features, that will not have as much variation in their geocode results. -Guidelines for shortening codes are in the [wiki](https://github.com/google/open-location-code/wiki/Guidance-for-shortening-codes). +Guidelines for shortening codes are in the [wiki](https://github.com/google/open-location-code/tree/main/docs/wiki/Guidance-for-shortening-codes.md). Recovering shortened codes works by providing the short code and a reference location. This does not need to be the same as the location used to shorten the diff --git a/docs/comparison.adoc b/docs/comparison.adoc index 1ceceb07..90dd7cca 100644 --- a/docs/comparison.adoc +++ b/docs/comparison.adoc @@ -1 +1 @@ -The document "An Evaluation of Location Encoding SystemsAn Evaluation of Location Encoding Systems" has been moved into the link://github.com/google/open-location-code/wiki/Evaluation-of-Location-Encoding-Systems[wiki]. +The document "An Evaluation of Location Encoding Systems" has been moved into the link: https://github.com/google/open-location-code/tree/main/docs/wiki/Evaluation-of-Location-Encoding-Systems.md[wiki]. diff --git a/docs/wiki/Evaluation-of-Location-Encoding-Systems.asciidoc b/docs/wiki/Evaluation-of-Location-Encoding-Systems.asciidoc new file mode 100644 index 00000000..afd03328 --- /dev/null +++ b/docs/wiki/Evaluation-of-Location-Encoding-Systems.asciidoc @@ -0,0 +1,348 @@ +An Evaluation of Location Encoding Systems +========================================== +:toc: +:toc-placement: preamble +:icons: + +== Abstract + +Many parts of the world and more than half the world's urban population +lack street addresses <>. The falling prices of smartphones, and +their increasing adoption, could provide a solution that would allow GPS +location signals to be made visible and usable as addresses. To do this, +there needs to be a way for the location information to be encoded so that +people are able to communicate locations to each other. This document +explains the attributes that we feel are important to such an encoding +system, and evaluates a number of existing encoding systems against the +requirements. + +== Desired Attributes + +We spent some time debating what attributes a location code should have. The +list we came up with was, in no particular order: + + * Codes should be short enough that they can be memorised + * A code should be sufficient on its own, not requiring additional + information such as country name + * To prevent confusion, a place should have only one code + * Codes should not include easily confused characters (e.g., 0 and O, 8 and + B etc) + * Codes should not include profanity, or preferably, any words in any language + * It should be possible to look at two codes and tell if they are close + together and even the direction. This will help people find their way and + make the codes more usable; + * Codes should represent an area, not a point, where the size of the area + is variable + * Shortening a code should represent a larger area that contains the + original location. A side effect of this is that nearby codes will have a + common prefix; + * The code for a place should be deterministically generated, not requiring + any setup or application + * Codes should be able to be generated and decoded offline. Mobile data + networks may not be ubiquitous or cheap + * Codes should 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 should be published publicly and be free to use. + +== Latitude and longitude + +Latitude and longitude are signed numbers with different ranges. The order +in which they are used matters - if reversed, they will represent a +different location. + +To express a location to roughly 10 meter accuracy (five decimal places), +latitude and longitude require between 15 and 20 text characters +("0.39122,9.45225" to "-43.95134,-176.55053"). This is around double the +length of a typical telephone number. + +Latitude and longitude express a point location, and there is no universally +accepted way to provide a location of something that is not a point, such as +a football field, park or lake, other than by providing multiple points to +enclose an area. Truncation of latitude and longitude doesn't make any real +sense, since it just moves the location. + +Cheap GPS devices have existed for at least 14 years <>, and yet latitude +and longitude coordinates are still not widely used by people to specify +locations. We think that this shows latitude and longitude have too many +disadvantages to be adopted for a street addressing solution. + +== Geohash + +Geohash codes <> were designed to be used in short URLs to identify locations +<>. They use 32 characters in their symbol set made up of 0-9A-Z excluding +"A", "I", "L" and "O". This means that Geohash codes can include vowels (and +the digits "0" and "1" with a similar appearance to "0" and "I"). Geohash +can generate codes that include words ("DRUGGED"), almost words ("ZUR1CH") +and profanity. It also includes some easily confused characters, such as +both "8" and "B". + +Geohash codes represent areas. Truncating a code reduces the precision, expanding +the area with the expanded area containing the original point. + +The length of a Geohash code depends on the number of decimal places of the +coordinates. This can result in two codes, near each other, having differing +lengths and this could be confusing in a street addressing context. + +Geohash uses a binary algorithm that is quite elegant, but it results in +five discontinuities (places where nearby locations have dissimilar Geohash +codes) at longitude 180, longitude 0, the equator, and at the north and +south poles. Longitude 180 and the poles are acceptable due to the low +populations but the equator and longitude 0 have multiple population centers +along them . + +== Geohash-36 + +Geohash-36 codes are designed for URLs and electronic storage and +communication rather than human memory and conversation <>. + +Geohash-36 does not include vowels but does include both lower- and +upper-case versions of some letters ("b" and "B"). It also includes +characters that can be easily confused ("6" and "b", "8" and "B"). + +Geohash-36 is based on a 6x6 grid where each cell is identified by a +character. This causes codes over a boundary to be dissimilar even though +they may be neighbours: + +.9x, g2, g7 and G2 code locations compared +image::https://github.com/google/open-location-code/blob/master/docs/images/geohash36_grid.png[width=412,height=407,align="center"] + +With just two levels, we can see that the cell "g2" (red, upper left of the +cell marked g) is next to the cell 9X, but further from g7 (which is next to +G2). Using real Geohash-36 codes, "bdg345476Q" is next to "bdbtTVTXWB" but +several kilometers from "bdg3Hhg4Xd". + +Geohash-36 codes may be one character shorter than full Open Location Codes +for similar accuracies. + +The Geohash-36 definition includes an optional altitude specification, and +an optional checksum, neither of which are provided by Open Location Code. + +== MapCode + +MapCodes can be defined globally or within a containing territory +<>. The global codes are a similar length to Open Location Codes, +but codes defined within a territory are shorter than full Open Location +Codes, and a similar length to short Open Location Codes. + +To decode the identifiers, a data file needs to be maintained and +distributed. The identifiers are mostly ISO-3166 codes for the territory +names which can lead to issues in disputed areas. Not all territory names +are unique and the recommendation is to use a country-state (e.g., "US-AL") +identifier in these cases. + +MapCode codes represent points and cannot be truncated (although the +territory identifier may be omitted within the territory). This can get +codes as short as four characters, something Open Location Code can do but +only within very small areas. + +A single location can have multiple different codes. For example, Schiphol +Airport in Amsterdam has the code (without a territory identifier) +"VHWK5.G7YB", and codes (with territory identifiers) "NLD 8G.262", "NLD +DCC.J5H", and "NLD N3V5.4PZ". + +MapCode supports a variety of different character sets, e.g., Hindi, +Cyrillic, Greek. This increases usability in non-latin countries but causes +challenges distinguishing visually similar codes such as "HH.HH" from the +cyrillic "НН.НН". Open Location Code currently only supports a Latin +character set. + +== Open Post Code + +Open Post Codes <> can be defined globally or within a containing country +<>. The global codes are a similar length to Open Location +Codes, but codes defined within a country are shorter than full Open +Location Codes, and a similar length to short Open Location Codes. + +Four countries are defined: Ireland, Hong Kong, Yemen and India. + +Every location on the planet has a global code. Locations within the +countries where Open Post Code has been defined also have a local code. +These codes are completely dissimilar. For example, the global code +"942G85NLMX" is the same place as the Ireland code "JKQQQXPG". If a global +code is mistakenly entered as a country code, it will be valid but decode to +a different location, and vice versa. The area and aspect ratio of a global +code is not the same as the local code for the same coordinates, or a local +code in another country, since it is a result of the aspect ratio used to +enclose the country. + +Open Post Codes decode to an area, and when truncated, expand the area. Open +Post Codes can be truncated a single character at a time. + +Open Post Codes use a 5x5 grid, meaning that two different codes may be +closer together than two highly similar codes: + +.8x, H2, H6 and J2 code locations compared +image::https://github.com/google/open-location-code/blob/master/docs/images/openpostcode_grid.png[width=404,height=399,align="center"] + +With just two levels , we can see that the cell "H2" (red, upper left of the +cell marked "H") is next to the cell "8X", but comparatively far from "H6" +(which is next to "J2"). + +Using Open Post Codes for Ireland, "KFLLLRFT" is the house next to +"JKQQQXPG", but the more similar code "KFPLPX24" is a couple of kilometers +away. + +Open Post Codes have an optional checksum that can be used to distinguish +the country a code was generated for. + +== Natural Area Code + +Natural Area Code <> is a proprietary system that requires licenses to use +<>. The codes are made up of up to three parts, the first +provides the latitude, the second the longitude and an optional third part +the altitude as the arctangent of the altitude relative to the Earth's +radius in a suffix to a code <>. + +Natural Area Codes do not support truncating. Although shorter codes +represent larger areas, they do not necessarily share a prefix with the +codes inside them. For example, "J3 RQ" covers the city of Berlin, Germany, +and contains the code "J39NL RQLLB". + +The whitespace in the code is significant and removing it results in an +invalid code (since it cannot be split into latitude and longitude). The +codes do not include vowels, but do include "0" and "1" as well as +characters that are easily confused ("8" and "B"). + +Natural Area Codes have a discontinuity at longitude 180 and at the poles. + +== Maidenhead Locator System (MLS) + +Maidenhead Locator System codes explicitly represent areas, and can be +truncated in a similar way to Open Location Codes. The accuracy and length of the codes is similar. MLS cannot generate words, but it can generate sequences that may appear to be words (e.g. when reading "1" as "l") <>. + +Maidenhead Locator System codes are based on an interleaving of latitude and +longitude, and so are truncatable, and nearby locations have similar codes. +It is only formally defined to a length of 8 characters. + +== Web-based services + +There are a variety of web-based services that have recently been created, +such as link:http://www.mydoorhandle.com[MyDoorHandle], +link:http://www.what3words.com[What3Words] and link:http://www.zip.pr[Zippr]. + +These sites provide a code that when entered on their site or used in a URL +brings up a web page displaying the location. That much is similar to e.g., +Geohash, but in contrast to Geohash, codes for a place may not exist until +someone applies for them. Codes usually represent a point. + +The codes may be pseudo-randomly generated and so nearby places may have +completely different codes. It may be possible for multiple people to apply +for codes for the same location and for different codes to be generated. + +What3words codes use three words to represent 3x3 meter squares. Codes have +been assigned for all locations on the earth using a proprietary algorithm. +Single words can be purchased ("OneWord"). In late 2014 an offline SDK was +announced, although this does not support purchased OneWords. + +Making a mistake with a code may simply display somewhere else - for +example, on What3Words, "banana rabbit monkey" is a location in Argentina, +"banana monkey rabbit" is in Russia. + +Some services charge money either for granting a code, for resolving codes +or for allowing users to select their own short code. + +These systems do not work offline and have a single provider. They appear to +be more targeted towards being business directories, hosting additional +information such as contact details, photos etc in addition to the location. + +== Open Location Code + +We felt that the attributes of the above systems didn't sufficiently meet +our requirements. As a result, we defined a new coding system and termed it +Open Location Code; codes created using this system are referred to as 'plus codes' (see the link: docs/wiki/Naming-Guidelines[Naming Guidelines]). + +Plus codes are 10 to 11 characters long. They can also be used in a +short form of four to seven characters, similar to telephone numbers and +postcodes, within approximately 50km of the original location. Within +approximately 2.5km of the original location they can be shortened further, +to just four to five characters. + +To aid recognition and memorisation, we include a separator to break the code +into two parts, and to distinguish codes from postal codes. + +In their short form, plus codes have from four to seven characters. +These can be used on their own within 50km of the place, or globally by +providing a city or locality within that distance. Full plus code +require no other information to locate them. + +There is only one plus code for a given location and area size. +Different codes can be generated with different areas, but they will share +the leading characters. + +The Open Location Code characters exclude easily confused character pairs. +There is a risk that "VV" will be confused for "W" in handwritten messages +but we consider this to be unlikely, since that would change the length of a +code and this should be detected by the user or recipient. + +The character set for Open Location Code was selected out of over eight +billion possibilities, using a word list of 10,000 words from 30 languages. +All possible sets were scored on whether they could spell the test words, +and the most promising sets evaluated by hand. + +The character set used to form plus codes is not contiguous. This +is a result of removing easily confused characters, vowels and some other +characters. This does make manually comparing codes difficult, as one has to +remember whether there are characters between 9 and C in order to tell if +8FV9 is next to 8FVC. However, we think that this is justified by the +improved usability. + +Nearby places have similar plus codes. There are three +discontinuities, at longitude 180 and at the north and south poles, where +nearby locations can have very different codes, but due to the low +populations in these areas we feel this is an acceptable limitation. + +With some practice, it is possible to estimate the direction and even very +rough distances between two codes. Due to the way the codes are generated, +latitudes are clipped to be greater than or equal to -90 and less than 90 +degrees, making representing the exact location of the North Pole impossible +although it can be very closely approximated. + +Plus codes represent areas, and the size of the area depends on the +code length. The longer the code, the smaller and more accurate the area. + +Truncating a plus code increases the area and contains the +original location. + +The codes are based on a simple encoding of latitude and longitude. The code +for a place can be looked up by anyone and does not require any setup or +configuration. + +Plus codes can be encoded and decoded offline. + +Plus codes do not depend on any infrastructure, and so are not +dependent on any organisation or company for their continued existence or +usage. + +We are publishing the algorithm and making open source implementations +available for anyone to use. + +[bibliography] +== References + +- [[[farvacque]]] Farvacque-Vitkovic C, Godin L, Leroux H, Verdet F, Chavez +R 2005. Street Addressing and the Management of Cities, World Bank, 2005 + +- [[[etrex]]] "One of the most popular of the Garmin handheld GPS +receivers, the compact eTrex series, was introduced in 2000". In Wikipedia. + +- [[[garmin]]] Retrieved October 15 2014 from http://en.wikipedia.org/wiki/Garmin + +- [[[geohash32]]] In Wikipedia. Retrieved October 15 2014 from http://en.wikipedia.org/wiki/Geohash + +- [[[geohash-site]]] http://geohash.org/ Retrieved October 15 2014. + +- [[[geohash36]]] In Wikipedia. Retrieved October 15 2014 from http://en.wikipedia.org/wiki/Geohash-36 + +- [[[mapcode]]] http://www.mapcode.com/ Retrieved October 15 2014. + +- [[[openpostcode]]] In Wikipedia. Retrieved October 15 2014 from http://en.wikipedia.org/wiki/Postal_addresses_in_the_Republic_of_Ireland + +- [[openpostcode-site]] http://www.openpostcode.org/ Retrieved October 15 2014. + +- [[[naclicense]]] Legal and Licensing Retrieved October 15 2014 from http://www.nacgeo.com/nacsite/licensing/ + +- [[[nac]]] The Natural Area Coding System Retrieved October 15 2014 from http://www.nacgeo.com/nacsite/documents/nac.asp + +- [[nac-site]] http://nacgeo.com Retrieved October 15 2014. + +- [[[mls]]] In Wikipedia. Retrieved October 15 2014 from http://en.wikipedia.org/wiki/Maidenhead_Locator_System \ No newline at end of file diff --git a/docs/wiki/FAQ.md b/docs/wiki/FAQ.md new file mode 100644 index 00000000..28443c86 --- /dev/null +++ b/docs/wiki/FAQ.md @@ -0,0 +1,79 @@ +# Open Location Code Frequently Asked Questions + +## Table Of Contents +* [Background](#background) + * ["plus codes" or "Open Location Code"?](#plus-codes-or-open-location-code) + * [What are they for?](#what-are-they-for) + * [Why not use street addresses?](#why-not-use-street-addresses) + * [Why not use latitude and longitude?](#why-not-use-latitude-and-longitude) +* [Plus code digital addresses](#plus-code-digital-addresses) + * [Plus code addresses in Google Maps](#plus-code-addresses-in-google-maps) + * [Plus code addresses in high-rise buildings](#plus-code-addresses-in-high-rise-buildings) + * [Plus code precision](#plus-code-precision) + + + +## Background + +### "plus codes" or "Open Location Code"? + +The software library (and this GitHub project) is called "Open Location Code", because it's a location code that is open source. The codes it generates are called "plus codes" because they have a plus sign in them. + +### What are they for? + +Plus codes provide a short reference to any location. 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. + +### Why not use street addresses? + +A lot of rural areas can be far away from roads, and people still want to be able to refer to specific locations. Also, at lot of the roads in the world don't have names, and so locations along those roads don't have addresses. There is an estimate by the World Bank that the majority of urban roads don't have names. + +Street-based addressing projects are expensive and slow, and haven't made much of a dent in this problem. Plus codes can be assigned rapidly and because they can be used immediately can solve the addressing problem quickly and cheaply. + +### Why not use latitude and longitude? + +One answer is that if latitude and longitude were a practical solution, people would already be using them. The problem with latitude and longitude is that they are two numbers, possibly signed, with a lot of digits, and the order is important. + +But latitude and longitude, and many other systems such as MGRS, geocodes, etc, also have the problem that they do not look like addresses. 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. This hierarchy is important since it makes it easy to determine if something is near or far without having to understand the whole thing. You can tell if it's in a different city without having to know the street name. + +### Why is Open Location Code based on latin characters? + +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. We selected Latin characters as the most common second-choice character set in these locations. 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. + +## Plus code digital addresses + +Plus code digital addresses use known address information, like country, state, city, and then use the plus code to provide the final information. 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. + +Any city or place name within approximately 30-50 km can be used to recover the original location. + +### Reference location dataset + +The open source libraries support conversion to/from addresses using the latlng of the reference location. Callers will need to convert place names to/from latlng using a geocoding system. + +Providing a global dataset isn't within scope of this project. For a potential free alternative, see [Open Street Map](https://wiki.openstreetmap.org/) and derived geocoding service [Nominatim](https://nominatim.org/). + +### Plus code addresses in Google Maps + +Google Maps displays plus code addresses on all entries. 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. + +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.) + +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. + +### Plus code addresses of high-rise buildings + +Plus codes don't include the floor or apartment in high-rise buildings. 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" + +The reason for this is that plus codes need to be created without knowing specifically what is there. 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. + +### Plus code precision + +The precision of a plus code is indicated by the number of digits after the "+" sign. + +* Two digits after the plus sign is an area roughly 13.7 by 13.7 meters; +* Three digits after the plus sign is an area roughly 2.7 by 3.5 meters; +* Four digits after the plus sign is an area roughly 0.5 by 0.8 meters. + +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. + +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. + diff --git a/docs/wiki/Field-Data-Collection-Practices.md b/docs/wiki/Field-Data-Collection-Practices.md new file mode 100644 index 00000000..7598f33d --- /dev/null +++ b/docs/wiki/Field-Data-Collection-Practices.md @@ -0,0 +1,94 @@ +# Field Collection of Plus Code Locations +[](https://play.google.com/store/apps/details?id=org.odk.collect.android) + +## Summary + +Collecting locations of equipment, buildings, homes etc from the field, and obtaining the plus codes, is a common problem. + +[Open Data Kit](https://opendatakit.org) is a suite of free and open source software to support collecting, managing and using data. [Open Data Kit Collect](https://play.google.com/store/apps/details?id=org.odk.collect.android) (ODK Collect) is a free, open source app available in the Google Play Store for customizable data collection in an offline environment. + +This document explains how to get started with ODK to collect location data and convert it to plus codes. + +**Note:** This process will collect latitude and longitude and convert them to global plus codes, e.g. 8FVC9G8F+6W. Converting these to plus code addresses (9G8F+6W Zurich, Switzerland) is out of scope of this data collection. (One way it could be done is using the [Google Maps Geocoding API](https://developers.google.com/maps/documentation/geocoding/intro).) + +## Overview + +First we will define a [form](https://docs.opendatakit.org/form-design-intro/) that specifies what data we want, and then use [ODK Collect](https://docs.opendatakit.org/collect-intro/), an Android app, to collect filled in forms. + +ODK Collect saves location information as latitude and longitude, so the final step will be to convert those to plus codes using the [plus code add-on for Google Sheets](https://gsuite.google.com/marketplace). + +## Requirements + +* ODK Collect runs on Android devices +* The field workers will need Google accounts (we're going to use Google Drive and Sheets). + +## Alternatives + +Other options for collecting this data might be to use Google Maps - manually long pressing on the map displays an address card, and expanding that shows the plus code. + +Alternatively, you could write an HTML5 web app or develop another mobile app. These could do the conversion from GPS coordinates to plus codes directly. However, we think that using Open Data Kit provides the fastest route to general functionality. + +## Using Open Data Kit + +Here is a [description of using ODK with Google Drive and Sheets](https://www.google.com/earth/outreach/learn/odk-collect-and-google-drive-integration-to-store-and-manage-your-data). + +This procedure can be followed exactly, or a slightly easier method to define the form is described below. + +## Online Form Editor + +That document uses a Google Sheet to define the form. This can be complicated to test and debug. A simpler way is to use the [online form editor](https://build.opendatakit.org/). + +This provides a drag and drop method to sequence the form questions and set the field names, list of options etc. + +You can build a basic flow with location collection, and include additional metadata such as the time of collection, the phone number etc. + +You will need to create a blank Google Sheet. Name one of the tabs "Form Submissions" or similar, copy the URL of that tab and set it as the `submission URL` in the form (using Edit -> Form Properties). + +The, save the form and export it (with File -> Export to XML), and then transfer that XML file to your Google Drive account. (Putting it in a folder together with the spreadsheet will make sharing those files to your field workers easy.) + +### Location Notes + +You can select whether to use Google Maps or OpenStreetMap in the general settings. You can also select whether to display the street map, or aerial imagery. + +ODK Collect will only use GPS locations when it can see a minimum number of satellites. If your field workers will be using it indoors, then the GPS location may not be available. Instead, you can set the field to not use GPS but allow a [user entered location](https://docs.opendatakit.org/form-question-types/#geopoint-with-user-selected-location) - but that will not collect accuracy or altitude, and may also be inaccurate. + +A better solution is to use the manual location as a fallback to GPS. You can have one question that uses the GPS location (with or without a map), and a second question that gets the location manually, and only show that question if the GPS is not available, or the location accuracy was poor. + +If using the online editor, enter the following in the **Relevance** field for the manual location field: +``` +not(boolean(/data/gps_location)) or number(/data/gps_location)>15 +``` + +(This assumes the data name of the GPS location field is `gps_location`.) + +If building your form in a spreadsheet, put the following in the **survey** tab: + +| type | name | label | relevant | appearance | +|------|------|-------|----------|------------| +| geopoint | gps_location | GPS location | | maps +| geopoint | manual_location | Manual location | `not(boolean(${gps_location})) or number(${gps_location})>15` | placement-map + +# Configuring ODK Collect + +Install and configure ODK Collect as described in the [document](https://www.google.com/earth/outreach/learn/odk-collect-and-google-drive-integration-to-store-and-manage-your-data). + +The document also describes how to use it and upload completed forms to the Google Sheet. + +# Converting Locations To Plus Codes + +ODK uploads locations to the sheet using three fields: +* location (decimal degrees) +* altitude (set to zero for manual locations) +* accuracy (set to zero for manual locations) + +To convert these to plus codes, install the Google Sheets plus code add-on from the [G Suite Marketplace](https://gsuite.google.com/marketplace). You can convert a column of locations into their corresponding plus codes using the formula: +``` +=PLUSCODE(B:B) +``` +This will use the default precision code length, 10 digits. If you need a different precision, specify the code length in the formula: +``` +=PLUSCODE(B:B, 11) +``` +Installing and using the Google Sheets Plus Codes add-on is covered in a series of videos: + +[![Google Sheets Plus Codes add-on video playlist](https://i.ytimg.com/vi/min-u1w4SOQ/hqdefault.jpg)](https://www.youtube.com/watch?v=n9kJC5qVeS0&list=PLaBfOq9xgeeBgOLyKnw8kvpFpZ_9v_sHa) diff --git a/docs/wiki/Guidance-for-shortening-codes.md b/docs/wiki/Guidance-for-shortening-codes.md new file mode 100644 index 00000000..8f426946 --- /dev/null +++ b/docs/wiki/Guidance-for-shortening-codes.md @@ -0,0 +1,17 @@ +Shortening codes is a key feature that aids their usability. + +Being able to say _WF8Q+WF, Praia_ is significantly easier than remembering and using _796RWF8Q+WF_. With that in mind, how do you choose the locality to use as a reference? + +Ideally, you need to use both the center point and the bounding box. + +Given a global code, _796RWF8Q+WF_, you can eliminate the first **four** digits of the code if: + * The center point of the feature is within **0.4** degrees latitude and **0.4** degrees longitude + * The bounding box of the feature is less than **0.8** degrees high and wide. + +If there is no suitable locality close enough or small enough, you can eliminate the first **two** digits of the code if: + * The center point of the feature is within **8** degrees latitude and **8** degrees longitude + * The bounding box of the feature is less than **16** degrees high and wide. + +These values are are chosen to allow for different geocoder backends placing localities in slightly different positions. Although they can be slightly increased there will be a risk that a shortened code will recover to a different location than the original, and people misdirected. + +Note: Usually your feature will be a town or city, but you could also use geographical features such as lakes or mountains, if they are the best local reference. If a settlement (such as neighbourhood, town or city) is to be used, you should choose the most prominent feature that meets the requirements, to avoid using obscure features that may not be widely known. \ No newline at end of file diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 00000000..66e7651f --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,28 @@ +# Welcome to the Open Location Code wiki! + +The wiki is where you can find out information about using the software, the codes, or the API. + +## Wiki pages +### Common pages +* [Frequently Asked Questions (FAQ)](https://github.com/google/open-location-code/tree/main/docs/wiki/FAQ.md) +* [Naming Guidelines](https://github.com/google/open-location-code/tree/main/docs/wiki/Naming-guidelines.md) +### Specification and technical implementation +* [Open Location Code specification](https://github.com/google/open-location-code/blob/master/docs/specification.md) +* [Open Location Code Overview](https://github.com/google/open-location-code/blob/master/docs/olc_definition.adoc) +* [An Evaluation of Location Encoding Systems](https://github.com/google/open-location-code/tree/main/docs/wiki/Evaluation-of-Location-Encoding-Systems) +* [Guidance for shortening codes](https://github.com/google/open-location-code/tree/main/docs/wiki/Guidance-for-shortening-codes) +### Technical +* [Supporting plus codes in GIS]([https://github.com/google/open-location-code/tree/main/docs/wiki/Supporting-plus-codes-in-GIS) +* [Supporting plus codes in an app](https://github.com/google/open-location-code/tree/main/docs/wiki/Supporting-plus-codes-in-your-app) + +### Tools +* [Using plus codes in spreadsheets](Using-plus-codes-in-spreadsheets) +* [Field Data Collection Practices](https://github.com/google/open-location-code/tree/main/docs/wiki/Field-Data-Collection-Practices) +* [Display the plus code grid over maps](https://grid.plus.codes) (not a wiki page) + + +## About plus codes + +Plus codes are a digital addressing technology that aims to help people answer the question "where are you?". + +Developed by Google, this technology is open and free for anyone to use. diff --git a/docs/wiki/Naming-guidelines.md b/docs/wiki/Naming-guidelines.md new file mode 100644 index 00000000..c16cb84a --- /dev/null +++ b/docs/wiki/Naming-guidelines.md @@ -0,0 +1,28 @@ +# Why have guidelines? +These guidelines are offered so that people see a consistent reference to the codes and technology. This will make it easier for them to understand what they are being shown or asked for. + +We have chosen two names - one for the technology and one for the actual codes. The name for the codes reflects and reinforces the importance of the plus symbol, which is how the codes can be recognised. + +# Plus Codes +When referring to Plus Codes in English, the **only** term that should be used is "Plus Code", in Title Case. + +Some examples of usage are: +* "My Plus Code is CX37+M9." +* "I gave your Plus Code to the cab driver and he found the way without any problems." +* "Will the postcard arrive if I put your Plus Code as the address?" +* "Enter your Plus Code or street address here." + +## Global and local codes + +Codes that can be decoded to a lat/lng on their own, e.g. 796RWF8Q+WF are referred to as global codes. + +The shortened codes, e.g., WF8Q+WF are referred to as local codes, because they work within a local area. + +# Open Location Code +When discussing with organisations or developers, refer to the library, algorithm and technology as "Open Location Code". This can be abbreviated to OLC, is capitalised, and shouldn't be translated. + +It shouldn't be used to refer to the actual codes - don't say "Open Location Codes" for example. + +# Summary +Having consistent names and presentation will make it easier for people to recognise what is meant, and make it easier for them to use and benefit from the project. + diff --git a/docs/wiki/Other-Implementations.md b/docs/wiki/Other-Implementations.md new file mode 100644 index 00000000..24852c54 --- /dev/null +++ b/docs/wiki/Other-Implementations.md @@ -0,0 +1,45 @@ +This page lists implementations of the Open Location Code library by third parties. This will usually be implementations in languages other than the set in this repository. + +# C# (.NET standard) + +https://github.com/JonMcPherson/open-location-code + +# Common Lisp + +https://github.com/ralph-schleicher/open-location-code + +# EMACS + +https://gitlab.liu.se/davby02/olc + +# R + +https://github.com/Ironholds/olctools + +# Swift/Objective C + +## Curbmap + +https://github.com/curbmap/OpenLocationCode-swift + +Curbmap has a Swift 4.x and 3.x implementation. + +Properties: +* Can be built as a Framework for iOS. +* Available via [CocoaPods](https://cocoapods.org/pods/OpenLocationCode) (`pod OpenLocationCode`). +* Includes Objective-C Bridging Interface. +* Does not implement the complete [Open Location Code API](../API.txt) (`recoverNearest` API method is not implemented). +* Not validated using the OLC [test data](../test_data). + +## Open Location Code for Swift and Objective-C + +https://github.com/google/open-location-code-swift + +This library supports Objective-C for iOS, macOS, tvOS, and watchOS. +It is implemented in Swift 5.0 with a complete [Objective-C interface](https://github.com/google/open-location-code-swift#objective-c-code-example). + +It can be built as a Framework, supports [Carthage](https://github.com/Carthage/Carthage), and is available via [CocoaPods](https://cocoapods.org/pods/OpenLocationCodeFramework). + +# Typescript + +https://github.com/tspoke/typescript-open-location-code \ No newline at end of file diff --git a/docs/wiki/Plus-codes-API.md b/docs/wiki/Plus-codes-API.md new file mode 100644 index 00000000..ed15d8a0 --- /dev/null +++ b/docs/wiki/Plus-codes-API.md @@ -0,0 +1,266 @@ +# API Developer's Guide + +### Table of Contents +* [Functionality](#functionality) +* [API Request Format](#api-request-format) +* [Example Requests](#example-requests) + * [Locality Requests](#locality-requests) +* [API Keys](#api-keys) + * [Obtaining A Google API Key](#obtaining-a-google-api-key) + * [Securing Your API Key](#securing-your-api-key) + * [Securing Your API Key With An HTTP Referrer](#securing-your-api-key-with-an-http-referrer) + * [Allowing Multiple Referrers](#allowing-multiple-referrers) + +> This API is *experimental*. As of December 2016, we are soliciting feedback on the functionality, in order to inform proposals to geocoding API providers such as Google. You can discuss the API in the [public mailing list](https://groups.google.com/forum/#!forum/open-location-code) or create an issue in the [issue tracker](https://github.com/google/open-location-code/issues/new?labels=api&assignee=drinckes). + +> If the API needs to be turned off, or there are other important messages, they will be returned in the JSON result in the field `error_message`, described on this page, or sent to the [mailing list](https://groups.google.com/forum/#!forum/open-location-code). + +> Feb/March 2017: Google API keys are required for the generation of short codes and searching by address. See the [API Keys](#api-keys) section and the `key` parameter. + +> October 2018: v2 of the API is launched that returns the same localities that are displayed in Google Maps. A side effect of this update is that the API should be slightly faster, and if API keys are used, the cost should be reduced. + +## History + +* December 2016. v1 of API launched +* October 2018. v2 of API launched and made default. + +## Functionality + +The API provides the following functions: + +* Conversion of a latitude and longitude to a plus code (including the bounding box and the center); +* Conversion of a plus code to the bounding box and center. + +Additionally, it can use the [Google Geocoding API](https://developers.google.com/maps/documentation/geocoding/intro) to: + +* Include short codes and localities in the returned plus code (such as "WF8Q+WF Praia, Cape Verde" for "796RWF8Q+WF"); +* Handle converting from a street address or business name to the plus code; +* Handle converting a short code and locality to the global code and coordinates. + +The results are provided in JSON format. The API is loosely modeled on the [Google Geocoding +API](https://developers.google.com/maps/documentation/geocoding/intro). + +## API Request Format + +A Plus codes API request takes the following form: + +`https://plus.codes/api?parameters` + +**Note**: URLs must be [properly encoded](https://developers.google.com/maps/web-services/overview#BuildingURLs) (specifically, `+` characters must be encoded to `%2B`). + +**Required parameter:** + +* `address` — The address to encode. This can be any of the following (if the `ekey` parameter is also provided): + * A latitude/longitude + * A street address + * A global code + * A local code and locality + * ~~A local code and latitude/longitude~~ (Deprecated in v2 of the API) + +**Recommended parameters:** + +* `key` — An Google API key. See [API Keys](#api-keys). If this parameter is omitted, only latitude/longitude and global codes can be used in the `address` parameter, and locality information will not be returned. (This can also be specified using `ekey`.) +* `email` — Provide an email address that can be used to contact you. +* `language` — The language in which to return results. This won't affect the global code, but it will affect the names of any features generated, as well as the address used for the local code. + * If `language` is not supplied, results will be provided in English. + +## Example Requests (no Google API key) + +The following two requests show how to convert a latitude and longitude to a code, or how to get the geometry of a global code: + +* https://plus.codes/api?address=14.917313,-23.511313&email=YOUR_EMAIL_HERE +* https://plus.codes/api?address=796RWF8Q%2BWF&email=YOUR_EMAIL_HERE + +Both of these requests will return the global code, it's geometry, and the center: + +```javascript +{ + "plus_code": { + "global_code": "796RWF8Q+WF", + "geometry": { + "bounds": { + "northeast": { + "lat": 14.917375000000007, + "lng": -23.511250000000018 + }, + "southwest": { + "lat": 14.91725000000001, + "lng": -23.511375000000015 + } + }, + "location": { + "lat": 14.917312500000008, + "lng": -23.511312500000017 + } + }, + }, + "status": "OK" +} +``` + +## Example Requests (with Google API key) + +Here are some example requests. You must include your Google API key in the request for these to work fully: + +* https://plus.codes/api?address=14.917313,-23.511313&ekey=YOUR_ENCRYPTED_KEY&email=YOUR_EMAIL_HERE +* https://plus.codes/api?address=796RWF8Q%2BWF&ekey=YOUR_ENCRYPTED_KEY&email=YOUR_EMAIL_HERE +* https://plus.codes/api?address=WF8Q%2BWF%20Praia%20Cape%20Verde&ekey=YOUR_ENCRYPTED_KEY&email=YOUR_EMAIL_HERE + +These requests would all return: + +```javascript + + "plus_code": { + "global_code": "796RWF8Q+WF", + "geometry": { + "bounds": { + "northeast": { + "lat": 14.917375000000007, + "lng": -23.511250000000018 + }, + "southwest": { + "lat": 14.91725000000001, + "lng": -23.511375000000015 + } + }, + "location": { + "lat": 14.917312500000008, + "lng": -23.511312500000017 + } + }, + "local_code": "WF8Q+WF", + "locality": { + "local_address": "Praia, Cape Verde" + }, + }, + "status": "OK" +} +``` + +## JSON Response Format + +The JSON response contains two root elements: + +* `"status"` contains metadata on the request. Other status values are documented [here](https://developers.google.com/maps/documentation/geocoding/intro#StatusCodes). +* `"plus_code"` contains the plus code information for the location specified in `address`. + +> There may be an additional `error_message` field within the response object. This may contain additional background information for the status code. + +The `plus_code` structure has the following fields: +* `global_code` gives the global code for the latitude/longitude +* `bounds` provides the bounding box of the code, with the north east and south west coordinates +* `location` provides the centre of the bounding box. + +If a locality feature near enough and large enough to be used to shorten the code was found, the following fields will also be returned: +* `local_code` gives the local code relative to the locality +* `locality` provides the name of the locality using `local_address`. + +If the `ekey` encrypted key is not provided the following fields will not be returned: +* `local_code` +* `locality` +* `local_address` + +### Locality Requests + +The `address` parameter may match a large feature, such as: + +``` +https://plus.codes/api?address=Paris&ekey=YOUR_ENCRYPTED_KEY&email=YOUR_EMAIL_HERE +``` + +In this case, the returned code may not have full precision. This is because for large features, the returned code will be the **largest** code that fits entirely **within** the bounding box of the feature: + +```javascript +{ + "plus_code": { + "global_code": "8FW4V900+", + "geometry": { + "bounds": { + "northeast": { + "lat": 48.900000000000006, + "lng": 2.4000000000000057 + }, + "southwest": { + "lat": 48.849999999999994, + "lng": 2.3499999999999943 + } + }, + "location": { + "lat": 48.875, + "lng": 2.375 + } + } + }, + "status": "OK" +} +``` + +## API Keys + +### Obtaining A Google API Key +To search for addresses, return addresses, and return short codes and localities, the Plus Codes API uses the [Google Maps Geocoding API](https://developers.google.com/maps/documentation/geocoding/intro). If you want to be able to: +* search by address, +* search by short codes with localities, +* or have short codes and localities included in responses + +you *must* provide a Google API key in your request. To obtain a Google API key refer [here](https://developers.google.com/maps/documentation/geocoding/start#get-a-key). + +Important: +* The API key *must* have the Google Maps Geocoding API enabled +* The API key *must* not have any restrictions (referrer, IP address). (This is because it is used to call the web service API, which does not allow restrictions on the key.) + +Once you have your API key, you can specify it in requests using the `key` parameter, but you should read the next two sections on securing your key. + +### Securing Your API Key + +Google API keys have a free daily quota allowance. If other people obtain your key, they can make requests to any API that is enabled for that key, consuming your free quota, and if you have billing enabled, can incur charges. + +The normal way of securing API keys is setting restrictions on the host that can use it to call Google APIs. These methods won't work here, because the calls to the Google API are being done from the plus codes server. + +Instead, you can encrypt your Google API key, and use the encrypted value in the requests to the plus codes API. The plus codes server will decrypt the key and use the decrypted value to make the calls to Google. + +If anyone obtains your encrypted API key, they cannot use it to make direct requests to any Google API. (They can still use it to make requests to the plus codes API, see the next section for a solution.) + +For example, to protect the Google API key `my_google_api_key`, encrypt it like this: + +``` +https://plus.codes/api?encryptkey=my_google_api_key +``` + +The plus codes API will respond with: + +```javascript +{ + "encryption_message": "Provide the key in the key= parameter in your requests", + "key": "8Kr54rKYBj8l8DcTxRj7NkvG%2Fe%2FlwvEU%2F4M41bPX3Zmm%2FZX7XoZlsg%3D%3D", + "status": "OK" +} +``` + +### Securing Your API Key With An HTTP Referrer + +For extra security, you can encrypt a hostname with the key. When the plus codes server decrypts the key, it checks that the HTTP referrer matches the encrypted hostname. This prevents the encrypted key from being used from another host. + +For example, to protect the Google API key `my_google_api_key`, and require the HTTP referrer host to be `openlocationcode.com`, encrypt it like this: + +``` +https://plus.codes/api?referer=openlocationcode.com&encryptkey=my_google_api_key +``` + +The plus codes API will respond with: + +```javascript +{ + "encryption_message": "Provide the key in the key= parameter in your requests", + "key": "Nn%2BzIy2LOz7sptIe4tkONei3xfO7MUPSyYdoNanqv%2F1wgDaGvUryUDt8EPXRS4xzP%2F0b04b3J6%2BzFeeu", + "status": "OK" +} +``` + +#### Allowing Multiple Referrers + +If you need to use the same encrypted key from multiple different hosts, say `example1.com` and `example2.com`, include the hosts in the referer like this: + +``` +https://plus.codes/key?referer=example1.com|example2.com&key=my_google_api_key +``` diff --git a/docs/wiki/Supporting-plus-codes-in-GIS.md b/docs/wiki/Supporting-plus-codes-in-GIS.md new file mode 100644 index 00000000..1e341142 --- /dev/null +++ b/docs/wiki/Supporting-plus-codes-in-GIS.md @@ -0,0 +1,49 @@ +# Plus codes in GIS software + +This page provides information about using plus codes in GIS software. + +## Tile Service + +If you want to visualise the plus codes grid, you can use the [grid service](https://grid.plus.codes) to fetch the grid tiles. + +This is a shared service, and it may rate limit you. If you need to use the grid heavily, you can start your +own [tile_server](https://github.com/google/open-location-code/tree/master/tile_server). + +The tile service provides GeoJSON objects, one per plus codes square, or PNG images that can be added as an overlay. + +## Software + +### QGIS + +| precision level | intervals in degrees | +|-----|-----| +| 10 | 0.000125 | +| 8 | 0.0025 | +| 6 | 0.05 | +| 4 | 1 | +| 2 | 20 | + +We can generate the grid lines in QGIS. + +Just make sure your starting lat-long values are an exact multiple of the interval values for your chosen precision level you want. + +Example : Creating a grid with precision 6 : starting latitude cannot be 16.4563. Change it to 16.45 or 16.50 so that when you divide it by 0.05 it gives you an integer answer. + +In QGIS, you can generate a grid by clicking in the top Menu: Vector > Research tools > Vector Grid + +* Grid extent (xmin,xmax,ymin,ymax): 78.1,79,16.9,18.2 (in my example, a city in India) +* Set both lat and lon interval as per the precision level you want. So for precision level 6, enter 0.05 for both. +* You can set output as lines or polygons, your choice. Lines make simpler and smaller shapefiles. +* And that should generate the grid for you. You can save that layer as a shapefile in any format. + +Note that this will not put any information about the plus codes in your grid's metadata. They're just lines/boxes. + +But if you make polygons, then I can think of a roundabout way of adding plus code values to those polygons (I have not done this myself yet): + +* Generate a centroid layer (Vector > Geometry Tools > Polygon Centroid) from the grid-polygons layer. This will place points inside each grid box. (in a new points layer.) +* Install "Lat Lon Tools" plugin. +* That plugin can generate plus codes from points. So run it on the centroid layer you made. +* (And this I can't quite figure out yet) Figure out a way to move the meta field from the centroid layer to the grid polygons layer. + +There is a plugin for QGIS, [Lat Lon tools](https://github.com/NationalSecurityAgency/qgis-latlontools-plugin). + diff --git a/docs/wiki/Supporting-plus-codes-in-your-app.md b/docs/wiki/Supporting-plus-codes-in-your-app.md new file mode 100644 index 00000000..3511a9d1 --- /dev/null +++ b/docs/wiki/Supporting-plus-codes-in-your-app.md @@ -0,0 +1,72 @@ +# Supporting plus codes technology in apps and sites + +This page gives guidelines for how to support plus codes in a website or mapping application. These guidelines should make it clear that adding support for OLC is not onerous, but actually quite easy. + +> Note that with the availability of the [plus codes API](https://github.com/google/open-location-code/tree/main/docs/wiki/Plus-code-API), these instructions really only apply to apps that require offline support. If your app or site can rely on a network connection, integrating with the API will give a better solution. + +# Supporting plus codes for search + +To support plus codes for searching, there are three different cases: +* global codes, such as "796RWF8Q+WF" +* local codes, such as "WF8Q+WF" +* local codes with a locality, such as "WF8Q+WF Praia, Cabo Verde" + +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. + +## Supporting global codes + +Global codes can be recognised and extracted from a query using a regular expression: + + /(^|\s)([23456789C][23456789CFGHJMPQRV][23456789CFGHJMPQRVWX]{6}\+[23456789CFGHJMPQRVWX]{2,3})(\s|$)/?i + +This will extract (in capturing group **2**) a global code at the start or end of a string, or enclosed with spaces. It will not match a global code embedded in a string such as "777796RWF8Q+WFFFFFFF". + +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. + +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. + +## Supporting local codes + +A variant of the global code regex can be used to check whether a location query includes a local code: + + /(^|\s)([23456789CFGHJMPQRVWX]{4,6}\+[23456789CFGHJMPQRVWX]{2,3})(\s|$)/?i + +If the query matches, *and the user has not entered any other text*, then another location must be used to recover the original code. 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. + +If there is no map, you can use the device location. 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. + +## Supporting local codes with localities + +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). 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. + +## Displaying the result + +If the user specified a plus code in their query, the result should match. That is, it is easier to understand if they enter a plus code to get a plus code displayed as the result. 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. + +# Computing plus codes for places + +Superficially computing plus codes for places is trivial. All that is needed is to call the `encode()` method on the coordinates, and then to display the code. + +The problem is that this only displays the global code, not the more convenient and easy to remember local code. But to display the local code, you need to do two things: + +* Compute the locality name +* Ensure that the locality is located near enough + +## Computing a locality name +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. + +Make a call to a reverse geocoding backend, preferably one that returns structured information, and extract the town or city name. + +Some geocoding backends are more suitable than others, so you might need to perform some tests. + +## Ensuring the locality is near enough +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. This is likely to be its center, not the position of the plus code, and could be some distance away. + +You want it to be as close as possible, because other geocoding services are likely to position it slightly differently. 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. + +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. + +If the locality is near enough, you should display the local code and locality together. The `shorten()` method in the OLC library may remove 2, 4, 6 or even 8 characters, depending on how close the reference location is. Although all of these are valid, we recommend only removing the first 4 characters, so that plus codes have a consistent appearance. + +# Summary +Supporting plus codes in search use cases should not be a complex exercise. \ No newline at end of file diff --git a/docs/wiki/Using-plus-codes-in-spreadsheets.md b/docs/wiki/Using-plus-codes-in-spreadsheets.md new file mode 100644 index 00000000..d264a979 --- /dev/null +++ b/docs/wiki/Using-plus-codes-in-spreadsheets.md @@ -0,0 +1,16 @@ +Being able to work with plus codes in spreadsheets is, for most people, probably the easiest method to work with them in bulk. + +This page explains how you can access the Open Location Code functions from Excel, LibreOffice or Google Spreadsheets. + +## Google Sheets + +There is an [add-on for Google Sheets](https://gsuite.google.com/marketplace/app/plus_codes/604254879289) that allows you to create plus codes from latitude and longitude coordinates, and to decode them as well. + +The [plus codes youtube channel](https://www.youtube.com/c/pluscodes) has some [videos showing how to install and use the add-on](https://www.youtube.com/playlist?list=PLaBfOq9xgeeBgOLyKnw8kvpFpZ_9v_sHa). + +## Excel/LibreOffice + +VBA script and instructions are checked into github [here](https://github.com/google/open-location-code/tree/master/visualbasic). + +LibreOffice does sometimes have problems. This may be due to slightly unreliable VBA support in some versions. + diff --git a/docs/wiki/Who-supports-OLC?.md b/docs/wiki/Who-supports-OLC?.md new file mode 100644 index 00000000..0c4ab0d5 --- /dev/null +++ b/docs/wiki/Who-supports-OLC?.md @@ -0,0 +1,18 @@ +This page lists the sites, apps and organisations that support Open Location Code. + +# Organisations + +* [Correios de Cabo Verde](correios.cv) (August 2016). Support plus codes for postal delivery. + +# Apps and sites + +* Google (Search, Maps) + * Search support for global and local codes (early 2016). + * Display of global codes in [Android](https://play.google.com/store/apps/details?id=com.google.android.apps.maps) and [iOS](https://itunes.apple.com/app/id585027354) maps (September 2016). + * [Assistant integration](https://assistant.google.com/services/a/uid/000000706b4e2cf1?hl=en) (early 2018) +* [mapy.cz](mapy.cz) (mid 2016) Search support for global codes. +* www.waze.com (early 2018?) Search support for plus code addresses (global and local) +* www.locusmap.eu (early 2018) Supports using global codes to set the map location +* [OSMAnd](https://osmand.net/) OpenStreetMap based offline mobile maps and navigation - Supports displaying OLC as the "coordinates" of any point on earth. +* [QGIS](https://qgis.org/) via [Lat Lon Tools](https://plugins.qgis.org/plugins/latlontools/) plug in - good support, points to olc, olc to points +* [nicesi.com](https://nicesi.com/) (early 2019) Nicesi Location API support for global codes in [reverse geocoding service](https://nicesi.com/doc/#reverse-geocoding) \ No newline at end of file