Merge pull request #41 from google/drinckes-api-update

Update API.txt

Author: drinckes

API.txt

@@ -18,30 +18,25 @@ isValid:
   sequence or not.
 
   To be valid, all characters must be from the Open Location Code character
-  set with at most one separator. If the separator character is present, it
-  must be after four characters. If the prefix character is present, it must
-  be the first character.
+  set with exactly one separator. There must be an even number of at most
+  eight characters before the separator. (Zero characters before the
+  separator is valid.)
 
 isShort:
   The isShort method takes a single parameter, a string, and returns a
   boolean indicating whether the string is a valid short Open Location Code
   or not.
 
-  A short Open Location Code is a sequence created by removing the first
-  four or six characters from a full Open Location Code.
-
-  A code must be a possible sub-string of a generated Open Location Code, at
-  least four and at most seven characters long and not include a separator
-  character. If the prefix character is present, it must be the first
-  character.
+  A short Open Location Code is a sequence created by removing a even number
+  of characters from a full Open Location Code. The resulting code must still
+  include the separator character.
 
 isFull:
   Determines if a code is a valid full Open Location Code.
 
   Not all possible combinations of Open Location Code characters decode to
   valid latitude and longitude values. This checks that a code is valid and
-  also that the latitude and longitude values are legal. If the prefix
-  character is present, it must be the first character. If the separator
+  also that the latitude and longitude values are legal. If the separator
   character is present, it must be after four characters.
 
 encode:
@@ -55,43 +50,21 @@ decode:
     returns an object with the lower and upper latitude and longitude pairs,
     the center latitude and longitude, and the length of the original code.
 
-shortenBy4:
-    Passed a valid full 10 or 11 character Open Location Code and a latitude
-    and longitude, this tries to remove the first four characters. This will
-    only succeed if both the latitude and longitude are less than 0.25
-    degrees from the code center. (Up to 0.5 degrees difference would work,
-    the requirement for 0.25 degrees represents a safety margin for cases
-    where the coordinates have come from a geocoding system and where the
-    center of large entities, such as cities, is subject to debate.)
-
-    If not possible, the original code is returned. If trimming is possible,
-    the first four characters are removed and the subsequent characters are
-    returned with the prefix added.
-
-shortenBy6:
-    Passed a valid full 10 or 11 character Open Location Code and a latitude
-    and longitude, this tries to remove the first six characters. This will
-    only succeed if both the latitude and longitude are less than 0.0125
-    degrees from the code center. (Up to 0.025 degrees difference would
-    work, the requirement for 0.0125 degrees represents a safety margin for
-    cases where the coordinates have come from a geocoding system and where
-    the center of large entities, such as cities, is subject to debate.)
-
-    If not possible, the original code is returned. If trimming is possible,
-    the first six characters are removed and the subsequent characters are
-    returned with the prefix added.
+shorten:
+    Passed a valid full Open Location Code and a latitude and longitude this
+    removes as many digits as possible (up to a maximum of eight) such that
+    the resulting code is the closest matching code to the passed location.
+    A safety factor may be included.
+    
+    If the code cannot be shortened, the original full code should be
+    returned.
+    
+    Since the only really useful shortenings are removing the first four or
+    six characters, this method may be replaced with methods such as
+    shortenBy4 or shortenBy6.
 
 recoverNearest:
-    This method is passed a valid short Open Location Code (of four to seven
-    characters) and a latitude and longitude, and returns the nearest
-    matching full Open Location Code to the specified location.
-
-    The number of characters that will be prepended to the short code, where S
-    is the supplied short code and R are the computed characters, are:
-    SSSS    -> RRRR.RRSSSS
-    SSSSS   -> RRRR.RRSSSSS
-    SSSSSS  -> RRRR.SSSSSS
-    SSSSSSS -> RRRR.SSSSSSS
-    Note that short codes with an odd number of characters will have their
-    last character decoded using the grid refinement algorithm.
+    This method is passed a valid short Open Location Code and a latitude and
+    longitude, and returns the nearest matching full Open Location Code to
+    the specified location.