Package com.dna.jopt.member.unit.converter.openlocation

Class OpenLocationCode

java.lang.Object
com.dna.jopt.member.unit.converter.openlocation.OpenLocationCode
public final class OpenLocationCode extends Object
Convert locations to and from convenient short codes.

Open Location Codes are short, ~10 character codes that can be used instead of street addresses. The codes can be generated and decoded offline, and use a reduced character set that minimises the chance of codes including words.

This provides both object and static methods.

Create an object with: OpenLocationCode code = new OpenLocationCode("7JVW52GR+2V"); OpenLocationCode code = new OpenLocationCode("52GR+2V"); OpenLocationCode code = new OpenLocationCode(27.175063, 78.042188); OpenLocationCode code = new OpenLocationCode(27.175063, 78.042188, 11);

Once you have a code object, you can apply the other methods to it, such as to shorten: code.shorten(27.176, 78.05)

Recover the nearest match (if the code was a short code): code.recover(27.176, 78.05)

Or decode a code into its coordinates, returning a CodeArea object. code.decode()

Author:
Jiri Semecky, Doug Rinckes

  • Field Details

  • Constructor Details

    • OpenLocationCode

      public OpenLocationCode(String code)
      Creates Open Location Code object for the provided code.
      Parameters:
      code - A valid OLC code. Can be a full code or a shortened code.
      Throws:
      IllegalArgumentException - when the passed code is not valid.

    • OpenLocationCode

      public OpenLocationCode(double latitude, double longitude, int codeLength)
      Creates Open Location Code.
      Parameters:
      latitude - The latitude in decimal degrees.
      longitude - The longitude in decimal degrees.
      codeLength - The desired number of digits in the code.
      Throws:
      IllegalArgumentException - if the code length is not valid.

    • OpenLocationCode

      public OpenLocationCode(double latitude, double longitude)
      Creates Open Location Code with the default precision length.
      Parameters:
      latitude - The latitude in decimal degrees.
      longitude - The longitude in decimal degrees.

  • Method Details

    • getCode

      public String getCode()
      Returns the string representation of the code.
      Returns:
      The code.

    • encode

      public static String encode(double latitude, double longitude)
      Encodes latitude/longitude into 10 digit Open Location Code. This method is equivalent to creating the OpenLocationCode object and getting the code from it.
      Parameters:
      latitude - The latitude in decimal degrees.
      longitude - The longitude in decimal degrees.
      Returns:
      The code.

    • encode

      public static String encode(double latitude, double longitude, int codeLength)
      Encodes latitude/longitude into Open Location Code of the provided length. This method is equivalent to creating the OpenLocationCode object and getting the code from it.
      Parameters:
      latitude - The latitude in decimal degrees.
      longitude - The longitude in decimal degrees.
      codeLength - The number of digits in the returned code.
      Returns:
      The code.

    • decode

      public OpenLocationCode.CodeArea decode()
      Decodes OpenLocationCode object into OpenLocationCode.CodeArea object encapsulating latitude/longitude bounding box.
      Returns:
      A CodeArea object.

    • decode

      public static OpenLocationCode.CodeArea decode(String code) throws IllegalArgumentException
      Decodes code representing Open Location Code into OpenLocationCode.CodeArea object encapsulating latitude/longitude bounding box.
      Parameters:
      code - Open Location Code to be decoded.
      Returns:
      A CodeArea object.
      Throws:
      IllegalArgumentException - if the provided code is not a valid Open Location Code.

    • isFull

      public boolean isFull()
      Returns whether this OpenLocationCode is a full Open Location Code.
      Returns:
      True if it is a full code.

    • isFull

      public static boolean isFull(String code) throws IllegalArgumentException
      Returns whether the provided Open Location Code is a full Open Location Code.
      Parameters:
      code - The code to check.
      Returns:
      True if it is a full code.
      Throws:
      IllegalArgumentException

    • isShort

      public boolean isShort()
      Returns whether this OpenLocationCode is a short Open Location Code.
      Returns:
      True if it is short.

    • isShort

      public static boolean isShort(String code) throws IllegalArgumentException
      Returns whether the provided Open Location Code is a short Open Location Code.
      Parameters:
      code - The code to check.
      Returns:
      True if it is short.
      Throws:
      IllegalArgumentException

    • isPadded

      public static boolean isPadded(String code) throws IllegalArgumentException
      Returns whether the provided Open Location Code is a padded Open Location Code, meaning that it contains less than 8 valid digits.
      Parameters:
      code - The code to check.
      Returns:
      True if it is padded.
      Throws:
      IllegalArgumentException

    • shorten

      public OpenLocationCode shorten(double referenceLatitude, double referenceLongitude)
      Returns short OpenLocationCode from the full Open Location Code created by removing four or six digits, depending on the provided reference point. It removes as many digits as possible.
      Parameters:
      referenceLatitude - Degrees.
      referenceLongitude - Degrees.
      Returns:
      A short code if possible.

    • recover

      public OpenLocationCode recover(double referenceLatitude, double referenceLongitude)
      Returns an OpenLocationCode object representing a full Open Location Code from this (short) Open Location Code, given the reference location.
      Parameters:
      referenceLatitude - Degrees.
      referenceLongitude - Degrees.
      Returns:
      The nearest matching full code.

    • contains

      public boolean contains(double latitude, double longitude)
      Returns whether the bounding box specified by the Open Location Code contains provided point.
      Parameters:
      latitude - Degrees.
      longitude - Degrees.
      Returns:
      True if the coordinates are contained by the code.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • isValidCode

      public static boolean isValidCode(String code)
      Returns whether the provided string is a valid Open Location code.
      Parameters:
      code - The code to check.
      Returns:
      True if it is a valid full or short code.

    • isFullCode

      public static boolean isFullCode(String code)
      Returns if the code is a valid full Open Location Code.
      Parameters:
      code - The code to check.
      Returns:
      True if it is a valid full code.

    • isShortCode

      public static boolean isShortCode(String code)
      Returns if the code is a valid short Open Location Code.
      Parameters:
      code - The code to check.
      Returns:
      True if it is a valid short code.