com.mapcode

Class MapcodeCodec

java.lang.Object

com.mapcode.MapcodeCodec

public final class MapcodeCodec
extends Object

---------------------------------------------------------------------------------------------- Mapcode public interface. ---------------------------------------------------------------------------------------------- This class is the external Java interface for encoding and decoding mapcodes.

Method Summary

Modifier and Type	Method and Description
static Point	decode(String mapcode) Decode a mapcode to a Point.
static Point	decode(String mapcode, Territory defaultTerritoryContext) Decode a mapcode to a Point.
static List<Mapcode>	encode(double latDeg, double lonDeg) Encode a lat/lon pair to a mapcode with territory information.
static List<Mapcode>	encode(double latDeg, double lonDeg, Territory restrictToTerritory) Encode a lat/lon pair to a mapcode with territory information, for a specific territory.
static List<Mapcode>	encode(Point point)
static List<Mapcode>	encode(Point point, Territory restrictToTerritory)
static Mapcode	encodeToInternational(double latDeg, double lonDeg) Encode a lat/lon pair to its unambiguous, international mapcode.
static Mapcode	encodeToInternational(Point point)
static Mapcode	encodeToShortest(double latDeg, double lonDeg, Territory restrictToTerritory) Encode a lat/lon pair to its shortest mapcode with territory information.
static Mapcode	encodeToShortest(Point point, Territory restrictToTerritory)
static boolean	isNearMultipleBorders(Point point, Territory territory) Is coordinate near multiple territory borders?

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

encode

@Nonnull
public static List<Mapcode> encode(double latDeg,
                                            double lonDeg)
                                     throws IllegalArgumentException

Encode a lat/lon pair to a mapcode with territory information. This produces a non-empty list of mapcode, with at the very least 1 mapcodes for the lat/lon, which is the "International" mapcode. The returned result list will always contain at least 1 mapcode, because every lat/lon pair can be encoded. The list is ordered in such a way that the last result is the international code. However, you cannot assume that the first result is the shortest mapcode. If you want to use the shortest mapcode, use encodeToShortest(double, double, Territory). The international code can be obtained from the list by using: "results.get(results.size() - 1)", or you can use encodeToInternational(double, double), which is faster.

Parameters:

latDeg - Latitude, accepted range: -90..90.

lonDeg - Longitude, accepted range: -180..180.

Returns:

Non-empty, ordered list of mapcode information records, see Mapcode.

Throws:

IllegalArgumentException - Thrown if latitude or longitude are out of range.

encode

@Nonnull
public static List<Mapcode> encode(@Nonnull
                                            Point point)
                                     throws IllegalArgumentException

Throws:

IllegalArgumentException

encode

@Nonnull
public static List<Mapcode> encode(double latDeg,
                                            double lonDeg,
                                            @Nullable
                                            Territory restrictToTerritory)
                                     throws IllegalArgumentException

Encode a lat/lon pair to a mapcode with territory information, for a specific territory. This produces a potentially empty list of mapcodes (empty if the lat/lon does not fall within the territory for mapcodes). The returned result list will always contain at least 1 mapcode, because every lat/lon pair can be encoded. The list is ordered in such a way that the last result is the international code. However, you cannot assume that the first result is the shortest mapcode. If you want to use the shortest mapcode, use encodeToShortest(double, double, Territory).

Parameters:

latDeg - Latitude, accepted range: -90..90 (limited to this range if outside).

lonDeg - Longitude, accepted range: -180..180 (wrapped to this range if outside).

restrictToTerritory - Try to encode only within this territory, see Territory. May be null.

Returns:

List of mapcode information records, see Mapcode. This list is empty if no Mapcode can be generated for this territory matching the lat/lon.

Throws:

IllegalArgumentException - Thrown if latitude or longitude are out of range.

encode

@Nonnull
public static List<Mapcode> encode(@Nonnull
                                            Point point,
                                            @Nullable
                                            Territory restrictToTerritory)
                                     throws IllegalArgumentException

Throws:

IllegalArgumentException

encodeToShortest

@Nonnull
public static Mapcode encodeToShortest(double latDeg,
                                                double lonDeg,
                                                @Nonnull
                                                Territory restrictToTerritory)
                                         throws IllegalArgumentException,
                                                UnknownMapcodeException

Encode a lat/lon pair to its shortest mapcode with territory information.

Parameters:

latDeg - Latitude, accepted range: -90..90.

lonDeg - Longitude, accepted range: -180..180.

restrictToTerritory - Try to encode only within this territory, see Territory. Cannot be null.

Returns:

Shortest mapcode, see Mapcode.

Throws:

IllegalArgumentException - Thrown if latitude or longitude are out of range.

UnknownMapcodeException - Thrown if no mapcode was found for the lat/lon matching the territory.

encodeToShortest

@Nonnull
public static Mapcode encodeToShortest(@Nonnull
                                                Point point,
                                                @Nonnull
                                                Territory restrictToTerritory)
                                         throws IllegalArgumentException,
                                                UnknownMapcodeException

Throws:

IllegalArgumentException

UnknownMapcodeException

encodeToInternational

@Nonnull
public static Mapcode encodeToInternational(double latDeg,
                                                     double lonDeg)
                                              throws IllegalArgumentException

Encode a lat/lon pair to its unambiguous, international mapcode.

Parameters:

latDeg - Latitude, accepted range: -90..90.

lonDeg - Longitude, accepted range: -180..180.

Returns:

International unambiguous mapcode (always exists), see Mapcode.

Throws:

IllegalArgumentException - Thrown if latitude or longitude are out of range.

encodeToInternational

@Nonnull
public static Mapcode encodeToInternational(@Nonnull
                                                     Point point)
                                              throws IllegalArgumentException

Throws:

IllegalArgumentException

decode

@Nonnull
public static Point decode(@Nonnull
                                    String mapcode)
                             throws UnknownMapcodeException,
                                    IllegalArgumentException,
                                    UnknownPrecisionFormatException

Decode a mapcode to a Point. The decoding process may fail for local mapcodes, because no territory context is supplied (world-wide). The accepted format is: {mapcode} {territory-code} {mapcode}

Parameters:

mapcode - Mapcode.

Returns:

Point corresponding to mapcode.

Throws:

UnknownMapcodeException - Thrown if the mapcode has the correct syntax, but cannot be decoded into a point.

UnknownPrecisionFormatException - Thrown if the precision format is incorrect.

IllegalArgumentException - Thrown if arguments are null, or if the syntax of the mapcode is incorrect.

decode

@Nonnull
public static Point decode(@Nonnull
                                    String mapcode,
                                    @Nullable
                                    Territory defaultTerritoryContext)
                             throws UnknownMapcodeException,
                                    IllegalArgumentException,
                                    UnknownPrecisionFormatException

Decode a mapcode to a Point. A reference territory is supplied for disambiguation (only used if applicable). The accepted format is: {mapcode} {territory-code} {mapcode} Note that if a territory-code is supplied in the string, it takes preferences over the parameter.

Parameters:

mapcode - Mapcode.

defaultTerritoryContext - Default territory context for disambiguation purposes. May be null.

Returns:

Point corresponding to mapcode. Latitude range: -90..90, longitude range: -180..180.

Throws:

UnknownMapcodeException - Thrown if the mapcode has the right syntax, but cannot be decoded into a point.

UnknownPrecisionFormatException - Thrown if the precision format is incorrect.

IllegalArgumentException - Thrown if arguments are null, or if the syntax of the mapcode is incorrect.

isNearMultipleBorders

public static boolean isNearMultipleBorders(@Nonnull
                                            Point point,
                                            @Nonnull
                                            Territory territory)

Is coordinate near multiple territory borders?

Parameters:

point - Latitude/Longitude in degrees.

territory - Territory.

Returns:

true Iff the coordinate is near more than one territory border (and thus encode(decode(M)) may not produce M).