diff --git a/Documentation/Specification/API.md b/Documentation/Specification/API.md deleted file mode 100644 index eb02c08d..00000000 --- a/Documentation/Specification/API.md +++ /dev/null @@ -1,62 +0,0 @@ -# Open Location Code Reference API - -## Version History - -- Version 1.0.0 / 2014-10-27 / [Doug Rinckes](https://github.com/drinckes), Google / Philipp Bunge, Google - - Initial public release - -## Public methods - -The following public methods should be provided by any Open Location Code implementation, subject to minor changes caused by language conventions. - -Note that any method that returns an Open Location Code should return upper case characters. - -Methods that accept Open Location Codes as parameters should be case insensitive. - -### `isValid` - -The `isValid` method takes a single parameter, a string, and returns a boolean indicating whether the string is a valid Open Location Code sequence or not. - -To be valid, all characters must be from the Open Location Code 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 an 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. -Full codes must include the separator character and it must be after eight characters. - -### `encode` - -Encode a location into an Open Location Code. -This takes a latitude and longitude and an optional length. -If the length is not specified, a code with 10 digits and an additional separator character will be generated. - -### `decode` - -Decodes an Open Location Code into the location coordinates. This method takes a string. -If the string is a valid full Open Location Code, it returns an object with the lower and upper latitude and longitude pairs, the center latitude and longitude, and the length of the original code. - -### `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 six) 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 and a latitude and longitude, and returns the nearest matching full Open Location Code to the specified location. - diff --git a/Documentation/Specification/Short_Code_Guidance.md b/Documentation/Specification/Short_Code_Guidance.md deleted file mode 100644 index 38f6af84..00000000 --- a/Documentation/Specification/Short_Code_Guidance.md +++ /dev/null @@ -1,22 +0,0 @@ -# Short Code Guidance - -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/Documentation/Specification/specification.md b/Documentation/Specification/specification.md index bdb43c6b..7a262cf0 100644 --- a/Documentation/Specification/specification.md +++ b/Documentation/Specification/specification.md @@ -2,7 +2,7 @@ ## Input values -Open Location Code encodes two numbers into a single, short string. +Open Location Code encodes two numbers, latitude and longitude, in degrees, into a single, short string. The latitude and longitude should be WGS84 values. If other datums are used it must be stated and made clear that these will produce different locations if plotted. @@ -126,19 +126,87 @@ For example, 8FVC9G8F+6W has the center 47.365562,8.524813. The following table Note: A code that has been shortened will not necessarily have the same initial four digits as the reference location. -## Library Implementation Requirements +### Generating Short Codes -Open Location Code library implementations must provide: -* a method to convert a latitude and longitude into a 10 digit Open Location Code -* a method to decode a 10 digit Open Location Code into, at a minimum, the latitude and longitude of the south-west corner and the height and width -* a method to determine if a string is a valid sequence of Open Location Code characters -* a method to determine if a string is a valid full Open Location Code -* decode and validation methods must not be case-sensitive +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? -Open Location Code library implementations can provide: -* a method to convert a latitude and longitude into any valid length Open Location Code -* a method to decode any valid length Open Location Code, providing additional information such as center coordinates -* a method to to convert a valid Open Location Code into a short code, given a reference location -* a method to recover a full Open Location Code from a short code and a reference location. -* a method to determine if a string is a valid short Open Location Code +Ideally, you need to use both the bounding box of the locality, as well as its center point. +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. + +(These values are chosen because a four digit Open Location Code is 1x1 degrees.) + +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 chosen because a two digit Open Location Code is 20x20 degrees.) + +The values above are slightly smaller than the maximums to allow for different geocoder backends placing localities in slightly different positions. +Although they could be 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. +(Basically, prefer city or town over neighbourhood.) + +## API Requirements + +The following public methods should be provided by any Open Location Code implementation, subject to minor changes caused by language conventions. + +Note that any method that returns an Open Location Code should return upper case characters. + +Methods that accept Open Location Codes as parameters should be case insensitive. + +Capitalisation should follow the language convention, for example the method `isValid` in golang would be `IsValid`. + +Errors should be returned following the language convention. For example exceptions in Python and Java, `error` objects in golang. + +### `isValid` + +The `isValid` method takes a single parameter, a string, and returns a boolean indicating whether the string is a valid Open Location Code sequence. + +### `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. + + See [Short Codes](#short-codes) above. + +### `isFull` + +Determines if a code is a valid full (i.e. not shortened) 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 that the resulting latitude and longitude values are legal. +Full codes must include the format separator character and it must be after eight characters. + +### `encode` + +Encode a location into an Open Location Code. +This takes a latitude and longitude and an optional length. +If the length is not specified, a code with 10 digits (and the format separator character) will be returned. + +### `decode` + +Decodes an Open Location Code into the location coordinates. +This method takes a string. +If the string is a valid full Open Location Code, it returns: +- the latitude and longitude of the SW corner of the bounding box; +- the latitude and longitude of the NE corner of the bounding box; +- the latitude and longitude of the center of the bounding box; +- the number of digits in the original code. + +### `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 six) 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, methods such as `shortenBy4` or `shortenBy6` could be provided instead. + +### `recoverNearest` + +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.