Merge branch 'main' into integer_c

CONTRIBUTING.md

@@ -35,7 +35,7 @@ To make a suggestion [file an issue](https://github.com/google/open-location-cod
 
 If you are intending to implement, please see the [Contributing code](#contributing-code) section below for next steps.
 
-If you are adding Open Location Codes to your project, please contact the [Open Location Code Google Group](https://groups.google.com/forum/#!forum/open-location-code) so we can suggest how you can make the most of the codes.
+If you are adding the Open Location Code library to your project, please contact the [Open Location Code Google Group](https://groups.google.com/forum/#!forum/open-location-code) so we can suggest how you can make the most of the codes.
 
 ## Contributing code
 

Documentation/FAQ.md

@@ -4,29 +4,29 @@
 - [Open Location Code Frequently Asked Questions](#open-location-code-frequently-asked-questions)
   - [Table Of Contents](#table-of-contents)
   - [Background](#background)
-    - ["plus codes" or "Open Location Code"?](#plus-codes-or-open-location-code)
+    - ["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)
     - [Why is Open Location Code based on latin characters?](#why-is-open-location-code-based-on-latin-characters)
-  - [Plus code digital addresses](#plus-code-digital-addresses)
+  - [Plus Code digital addresses](#plus-code-digital-addresses)
     - [Reference location dataset](#reference-location-dataset)
-    - [Plus code addresses in Google Maps](#plus-code-addresses-in-google-maps)
-    - [Plus code addresses of high-rise buildings](#plus-code-addresses-of-high-rise-buildings)
-    - [Plus code precision](#plus-code-precision)
+    - [Plus Code addresses in Google Maps](#plus-code-addresses-in-google-maps)
+    - [Plus Code addresses of high-rise buildings](#plus-code-addresses-of-high-rise-buildings)
+    - [Plus Code precision](#plus-code-precision)
 
 
 
 ## Background
 
-### "plus codes" or "Open Location Code"?
+### "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.
+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.
+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?
@@ -36,7 +36,7 @@ Also, at lot of the roads in the world don't have names, and so locations along
 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.
+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?
 
@@ -50,14 +50,14 @@ 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 are aware that many of the countries where Plus 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
 
-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.
+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.
 
@@ -69,32 +69,31 @@ 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
+### 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.
+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.
+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 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"
+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 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
+### Plus Code precision
 
-The precision of a plus code is indicated by the number of digits after the "+" sign.
+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.
-
+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.

Documentation/README.md

@@ -19,8 +19,8 @@ The wiki is where you can find out information about using the software, the cod
 ### Technical
 
 * [An Evaluation of Location Encoding Systems](Reference/comparison.adoc)
-* [Supporting plus codes in GIS software](Reference/GIS_Software.md)
-* [Supporting plus codes in an app](Reference/App_Developers.md)
+* [Supporting Plus Codes in GIS software](Reference/GIS_Software.md)
+* [Supporting Plus Codes in an app](Reference/App_Developers.md)
 
 ### Tools
 

Documentation/Reference/App_Developers.md

@@ -1,14 +1,15 @@
-# Supporting plus codes technology in apps and sites
+# Supporting Plus Codes technology in apps and sites
 
-This page gives guidelines for how to support plus codes in a website or mapping application.
+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 [https://plus.codes website API](plus.codes_Website_API.md), 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
+# Supporting Plus Codes for search
+
+To support Plus Codes for searching, there are three different cases:
 
-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"
@@ -51,13 +52,13 @@ Use the location returned by your geocoding service as the reference location in
 
 ## 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.
+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
+# Computing Plus Codes for places
 
-Superficially computing plus codes for places is trivial.
+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.
@@ -77,17 +78,17 @@ Some geocoding backends are more suitable than others, so you might need to perf
 ## 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.
+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.
+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.
+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.
+Supporting Plus Codes in search use cases should not be a complex exercise.

Documentation/Reference/Field_Collection_Data_Practices.md

@@ -3,20 +3,20 @@
 
 ## Summary
 
-Collecting locations of equipment, buildings, homes etc from the field, and obtaining the plus codes, is a common problem.
+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.
+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).)
+**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).
+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
 
@@ -25,10 +25,10 @@ ODK Collect saves location information as latitude and longitude, so the final s
 
 ## 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.
+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.
+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
@@ -91,8 +91,8 @@ ODK uploads locations to the sheet using three fields:
 * 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:
+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)
 ```

Documentation/Reference/GIS_Software.md

@@ -1,15 +1,15 @@
-# Plus codes in GIS software
+# Plus Codes in GIS software
 
-This page provides information about using 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.
+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/blob/main/tile_server).
 
-The tile service provides GeoJSON objects, one per plus codes square, or PNG images that can be added as an overlay.
+The tile service provides GeoJSON objects, one per Plus Codes square, or PNG images that can be added as an overlay.
 
 ## Software
 
@@ -40,15 +40,15 @@ In QGIS, you can generate a grid by clicking in the top Menu: Vector > Research
 * 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.
+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):
+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.
+* 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.
 

Documentation/Reference/Plus_Code_Users.md

@@ -5,7 +5,7 @@ This page lists the sites, apps and organisations that support Plus Codes / Open
 # Organisations
 
 * [Correios de Cabo Verde](correios.cv) (August 2016).
-  Support plus codes for postal delivery.
+  Support Plus Codes for postal delivery.
 
 # Apps and sites
 
@@ -14,7 +14,7 @@ This page lists the sites, apps and organisations that support Plus Codes / Open
   * 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.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