lib/main/google/olc/README.md

   1 Open Location Code
   2 ==================
   3
   4 [![Build Status](https://api.travis-ci.org/google/open-location-code.svg?branch=master)](https://travis-ci.org/google/open-location-code)
   5 [![CDNJS](https://img.shields.io/cdnjs/v/openlocationcode.svg)](https://cdnjs.com/libraries/openlocationcode)
   6
   7 Open Location Code is a technology that gives a way of encoding location into a form that is
   8 easier to use than latitude and longitude. The codes generated are called plus codes, as their
   9 distinguishing attribute is that they include a "+" character.
  10
  11 The technology is designed to produce codes that can be used as a replacement for street addresses, especially
  12 in places where buildings aren't numbered or streets aren't named.
  13
  14 Plus codes represent an area, not a point. As digits are added
  15 to a code, the area shrinks, so a long code is more precise than a short
  16 code.
  17
  18 Codes that are similar are located closer together than codes that are
  19 different.
  20
  21 A location can be converted into a code, and a code can be converted back
  22 to a location completely offline.
  23
  24 There are no data tables to lookup or online services required. The
  25 algorithm is publicly available and can be used without restriction.
  26
  27 Links
  28 -----
  29  * [Demonstration site](http://plus.codes/)
  30  * [Mailing list](https://groups.google.com/forum/#!forum/open-location-code)
  31  * [Comparison of existing location encoding systems](https://github.com/google/open-location-code/wiki/Evaluation-of-Location-Encoding-Systems)
  32  * [Open Location Code definition](https://github.com/google/open-location-code/blob/master/docs/olc_definition.adoc)
  33
  34 Description
  35 -----------
  36
  37 Codes are made up of a sequence of digits chosen from a set of 20. The
  38 digits in the code alternate between latitude and longitude. The first
  39 four digits describe a one degree latitude by one degree longitude
  40 area, aligned on degrees. Adding two further digits to the code,
  41 reduces the area to 1/20th of a degree by 1/20th of a degree within the
  42 previous area. And so on - each pair of digits reduces the area to
  43 1/400th of the previous area.
  44
  45 As an example, the Parliament Buildings in Nairobi, Kenya are located at
  46 6GCRPR6C+24. 6GCR is the area from 2S 36E to 1S 37E. PR6C+24 is a 14 meter
  47 wide by 14 meter high area within 6GCR.
  48
  49 A "+" character is used after eight digits, to break the code up into two parts
  50 and to distinguish codes from postal codes.
  51
  52 There will be locations where a 10 digit code is not sufficiently precise, but
  53 refining it by a factor of 20 is i) unnecessarily precise and ii) requires extending
  54 the code by two digits. Instead, after 10 digits, the area is divided
  55 into a 4x5 grid and a single digit used to identify the grid square. A single
  56 grid refinement step reduces the area to approximately 3.5x2.8 meters.
  57
  58 Codes can be shortened relative to a location. This reduces the number of digits
  59 that must be remembered, by using a location to identify an approximate area,
  60 and then generating the nearest matching code. Shortening a code, if possible,
  61 will drop four or more digits from the start of the code. The degree to which a
  62 code can be shortened depends on the proximity of the reference location.
  63
  64 If the reference location is derived from a town or city name, it is dependent
  65 on the accuracy of the geocoding service. Although one service may place
  66 "Zurich" close to the Google office, another may move it by a hundred meters or
  67 more, and this could be enough to prevent the original code being recovered.
  68 Rather than a large city size feature to generate the reference location, it is
  69 better to use smaller, neighbourhood features, that will not have as much
  70 variation in their geocode results.
  71
  72 Guidelines for shortening codes are in the [wiki](https://github.com/google/open-location-code/wiki).
  73
  74 Recovering shortened codes works by providing the short code and a reference
  75 location. This does not need to be the same as the location used to shorten the
  76 code, but it does need to be nearby. Shortened codes always include the "+"
  77 character so it is simple to compute the missing component.
  78
  79  * 8F+GG is missing six leading characters
  80  * 6C8F+GG is missing four leading characters
  81
  82 Example Code
  83 ------------
  84
  85 The subdirectories contain sample implementations and tests for different
  86 languages. Each implementation provides the following functions:
  87
  88  * Test a code to see if it is a valid sequence
  89  * Test a code to see if it is a valid full code
  90    Not all valid sequences are valid full codes
  91  * Encode a latitude and longitude to a standard accuracy
  92    (14 meter by 14 meter) code
  93  * Encode a latitude and longitude to a code of any length
  94  * Decode a code to its coordinates: low, high and center
  95  * Shorten a full code relative to a location
  96  * Extend a short code relative to a location