mapcode-foundation · rijnb · May 11, 2018 · May 11, 2018 · May 11, 2018
diff --git a/README.md b/README.md
@@ -351,6 +351,12 @@ self-hosting this service.
 
 ## Release Notes
 
+### 2.4.7.0
+
+* Added `?country=` parameter for mapcode encoding, to limit the result list to a specific country, given
+as a 2- or 3-character ISO 3166 country code. (In contrast with `?territory=`, which is not always a country,
+but can be a state as well.)
+
 ### 2.4.6.0 - 2.4.6.2
 
 * Updated to new Mapcode library.

diff --git a/deployment/pom.xml b/deployment/pom.xml
@@ -23,7 +23,7 @@
     <parent>
         <groupId>com.mapcode</groupId>
         <artifactId>mapcode-rest-service</artifactId>
-        <version>2.4.6.2</version>
+        <version>2.4.7.0</version>
     </parent>
 
     <artifactId>deployment</artifactId>

diff --git a/pom.xml b/pom.xml
@@ -24,7 +24,7 @@
     <artifactId>mapcode-rest-service</artifactId>
 
     <packaging>pom</packaging>
-    <version>2.4.6.2</version>
+    <version>2.4.7.0</version>
 
     <name>Mapcode REST API Web Service</name>
     <description>
@@ -104,7 +104,7 @@
         <jsr305.version>3.0.2</jsr305.version>
         <junit.version>4.12</junit.version>
         <log4j.version>1.2.17</log4j.version>
-        <mapcode.version>2.4.6</mapcode.version>
+        <mapcode.version>2.4.7</mapcode.version>
         <mockito-core.version>2.18.3</mockito-core.version>
         <resteasy.version>3.5.1.Final</resteasy.version>
         <scala.version>2.12.6</scala.version>

diff --git a/resources/pom.xml b/resources/pom.xml
@@ -23,7 +23,7 @@
     <parent>
         <groupId>com.mapcode</groupId>
         <artifactId>mapcode-rest-service</artifactId>
-        <version>2.4.6.2</version>
+        <version>2.4.7.0</version>
     </parent>
 
     <artifactId>resources</artifactId>

diff --git a/service/pom.xml b/service/pom.xml
@@ -23,7 +23,7 @@
     <parent>
         <groupId>com.mapcode</groupId>
         <artifactId>mapcode-rest-service</artifactId>
-        <version>2.4.6.2</version>
+        <version>2.4.7.0</version>
     </parent>
 
     <artifactId>service</artifactId>

diff --git a/service/src/main/java/com/mapcode/services/MapcodeResource.java b/service/src/main/java/com/mapcode/services/MapcodeResource.java
@@ -54,6 +54,7 @@ enum ParamInclude {
     static final String PARAM_LON_DEG = "lonDeg";
     static final String PARAM_PRECISION = "precision";
     static final String PARAM_TERRITORY = "territory";
+    static final String PARAM_COUNTRY = "country";
     static final String PARAM_ALPHABET = "alphabet";
     static final String PARAM_CONTEXT = "context";
     static final String PARAM_TYPE = "type";
@@ -83,6 +84,9 @@ void convertLatLonToMapcode(
      * @param paramTerritory         Specifies a territory context to create a local mapcode for. This is only useful for local mapcodes.
      *                               If the mapcode cannot be created for the territory, an exception is thrown.
      *                               Range: any valid territory code, alpha or numeric.
+     * @param paramCountry           Specifies a country context to create a local mapcode for. See also 'paramTerritory'.
+     *                               If the mapcode cannot be created for the country, an exception is thrown.
+     *                               Range: any valid country code.
      * @param paramAlphabet          Alphabet. Range: any valid alphabet code, alpha or numeric.
      * @param paramInclude           Specifies whether to include the offset (in meters) from the mapcode center to the specified lat/lon.
      *                               Range: {@link ParamInclude}.
@@ -125,6 +129,11 @@ void convertLatLonToMapcode(
                             "is already set by the context of the application (for example, you are only interested " +
                             "in mapcodes for your country). If omitted, mapcodes for all territories are considered.")
             @QueryParam(PARAM_TERRITORY) @Nullable String paramTerritory,
+            @ApiParam(
+                    value = "(optional) Limit the returned mapcodes to this country. This is useful if the country " +
+                            "is already set by the context of the application (for example, you are only interested " +
+                            "in mapcodes for your country). If omitted, mapcodes for all countries are considered.")
+            @QueryParam(PARAM_COUNTRY) @Nullable String paramCountry,
             @ApiParam(hidden = true)
             @QueryParam(PARAM_CONTEXT) @Nullable String paramContextMustBeNull,
             @ApiParam(
@@ -156,6 +165,9 @@ void convertLatLonToMapcode(
      * @param paramTerritory         Specifies a territory context to create a local mapcode for. This is only useful for local mapcodes.
      *                               If the mapcode cannot be created for the territory, an exception is thrown.
      *                               Range: any valid territory code, alpha or numeric.
+     * @param paramCountry           Specifies a country context to create a local mapcode for. See also 'paramTerritory'.
+     *                               If the mapcode cannot be created for the country, an exception is thrown.
+     *                               Range: any valid country code.
      * @param paramAlphabet          Alphabet. Range: any valid alphabet code, alpha or numeric.
      * @param paramInclude           Specifies whether to include additional info in the result, such as the offset (in meters)
      *                               from the mapcode center to the specified lat/lon, or the encompassing rectangle.
@@ -176,6 +188,7 @@ void convertLatLonToMapcode(
             @PathParam(PARAM_TYPE) @Nullable String paramType,
             @QueryParam(PARAM_PRECISION) @DefaultValue("0") int paramPrecision,
             @QueryParam(PARAM_TERRITORY) @Nullable String paramTerritory,
+            @QueryParam(PARAM_COUNTRY) @Nullable String paramCountry,
             @QueryParam(PARAM_CONTEXT) @Nullable String paramContextMustBeNull,
             @QueryParam(PARAM_ALPHABET) @Nullable String paramAlphabet,
             @QueryParam(PARAM_INCLUDE) @DefaultValue("") @Nonnull String paramInclude,

diff --git a/service/src/main/java/com/mapcode/services/OnlyJsonResource.java b/service/src/main/java/com/mapcode/services/OnlyJsonResource.java
@@ -57,6 +57,7 @@ void convertLatLonToMapcodeJson(
             @PathParam(PARAM_LON_DEG) double paramLonDeg,
             @QueryParam(PARAM_PRECISION) @DefaultValue("0") int paramPrecision,
             @QueryParam(PARAM_TERRITORY) @Nullable String paramTerritory,
+            @QueryParam(PARAM_COUNTRY) @Nullable String paramCountry,
             @QueryParam(PARAM_CONTEXT) @Nullable String paramContextMustBeNull,
             @QueryParam(PARAM_ALPHABET) @Nullable String paramAlphabet,
             @QueryParam(PARAM_INCLUDE) @DefaultValue("") @Nonnull String paramInclude,
@@ -73,6 +74,7 @@ void convertLatLonToMapcodeJson(
             @PathParam(PARAM_TYPE) @Nullable String paramType,
             @QueryParam(PARAM_PRECISION) @DefaultValue("0") int paramPrecision,
             @QueryParam(PARAM_TERRITORY) @Nullable String paramTerritory,
+            @QueryParam(PARAM_COUNTRY) @Nullable String paramCountry,
             @QueryParam(PARAM_CONTEXT) @Nullable String paramContextMustBeNull,
             @QueryParam(PARAM_ALPHABET) @Nullable String paramAlphabet,
             @QueryParam(PARAM_INCLUDE) @DefaultValue("") @Nonnull String paramInclude,

diff --git a/service/src/main/java/com/mapcode/services/OnlyXmlResource.java b/service/src/main/java/com/mapcode/services/OnlyXmlResource.java
@@ -57,6 +57,7 @@ void convertLatLonToMapcodeXml(
             @PathParam(PARAM_LON_DEG) double paramLonDeg,
             @QueryParam(PARAM_PRECISION) @DefaultValue("0") int paramPrecision,
             @QueryParam(PARAM_TERRITORY) @Nullable String paramTerritory,
+            @QueryParam(PARAM_COUNTRY) @Nullable String paramCountry,
             @QueryParam(PARAM_CONTEXT) @Nullable String paramContextMustBeNull,
             @QueryParam(PARAM_ALPHABET) @Nullable String paramAlphabet,
             @QueryParam(PARAM_INCLUDE) @DefaultValue("") @Nonnull String paramInclude,
@@ -73,6 +74,7 @@ void convertLatLonToMapcodeXml(
             @PathParam(PARAM_TYPE) @Nullable String paramType,
             @QueryParam(PARAM_PRECISION) @DefaultValue("0") int paramPrecision,
             @QueryParam(PARAM_TERRITORY) @Nullable String paramTerritory,
+            @QueryParam(PARAM_COUNTRY) @Nullable String paramCountry,
             @QueryParam(PARAM_CONTEXT) @Nullable String paramContextMustBeNull,
             @QueryParam(PARAM_ALPHABET) @Nullable String paramAlphabet,
             @QueryParam(PARAM_INCLUDE) @DefaultValue("") @Nonnull String paramInclude,

diff --git a/service/src/main/java/com/mapcode/services/implementation/MapcodeResourceImpl.java b/service/src/main/java/com/mapcode/services/implementation/MapcodeResourceImpl.java
@@ -25,10 +25,7 @@
 import com.mapcode.services.dto.*;
 import com.mapcode.services.metrics.SystemMetricsCollector;
 import com.tomtom.speedtools.apivalidation.ApiDTO;
-import com.tomtom.speedtools.apivalidation.exceptions.ApiForbiddenException;
-import com.tomtom.speedtools.apivalidation.exceptions.ApiIntegerOutOfRangeException;
-import com.tomtom.speedtools.apivalidation.exceptions.ApiInvalidFormatException;
-import com.tomtom.speedtools.apivalidation.exceptions.ApiNotFoundException;
+import com.tomtom.speedtools.apivalidation.exceptions.*;
 import com.tomtom.speedtools.geometry.Geo;
 import com.tomtom.speedtools.geometry.GeoPoint;
 import com.tomtom.speedtools.objects.Tuple;
@@ -65,6 +62,9 @@ public class MapcodeResourceImpl implements MapcodeResource {
     private static final String API_ERROR_VALID_TERRITORY_CODES = Joiner.on('|').join(Arrays.stream(Territory.values()).
             collect(Collectors.toList()));
 
+    private static final String API_ERROR_VALID_COUNTRY_CODES = Joiner.on('|').join(Territory.allCountryISO2Codes()) +
+            '|' + Joiner.on('|').join(Territory.allCountryISO3Codes());
+
     private static final String API_ERROR_VALID_ALPHABET_CODES = Joiner.on('|').join(Arrays.stream(Alphabet.values()).
             collect(Collectors.toList()));
 
@@ -109,23 +109,26 @@ public void convertLatLonToMapcode(
             final double paramLonDeg,
             final int paramPrecision,
             @Nullable final String paramTerritory,
+            @Nullable final String paramCountry,
             @Nullable final String paramContextMustBeNull,
             @Nullable final String paramAlphabet,
             @Nonnull final String paramInclude,
             @Nonnull final String paramClient,
             @Nonnull final String paramAllowLog,
             @Nonnull final AsyncResponse response) throws ApiInvalidFormatException {
-        convertLatLonToMapcode(paramLatDeg, paramLonDeg, null, paramPrecision, paramTerritory, paramContextMustBeNull,
-                paramAlphabet, paramInclude, paramClient, paramAllowLog, response);
+        convertLatLonToMapcode(paramLatDeg, paramLonDeg, null, paramPrecision, paramTerritory, paramCountry,
+                paramContextMustBeNull, paramAlphabet, paramInclude, paramClient, paramAllowLog, response);
     }
 
+    @SuppressWarnings("NestedTryStatement")
     @Override
     public void convertLatLonToMapcode(
             final double paramLatDeg,
             final double paramLonDeg,
             @Nullable final String paramType,
             final int paramPrecision,
             @Nullable final String paramTerritory,
+            @Nullable final String paramCountry,
             @Nullable final String paramContextMustBeNull,
             @Nullable final String paramAlphabet,
             @Nonnull final String paramInclude,
@@ -164,13 +167,34 @@ public void convertLatLonToMapcode(
                         ", " + ApiConstants.API_PRECISION_MAX + ']');
             }
 
+            // Check if either paramTerritory or paramCountry is set (or neither).
+            if ((paramTerritory != null) && (paramCountry != null)) {
+                throw new ApiConflictException("Cannot specify both " + PARAM_TERRITORY + " and " + PARAM_COUNTRY);
+            }
+
             // Get the territory.
-            @Nullable final Territory territory;
-            try {
-                territory = (paramTerritory != null) ?
-                        resolveTerritory(StringEscapeUtils.unescapeHtml4(paramTerritory), null) : null;
-            } catch (final IllegalArgumentException ignored) {
-                throw new ApiInvalidFormatException(PARAM_TERRITORY, paramTerritory, API_ERROR_VALID_TERRITORY_CODES);
+            @Nullable Territory territory = null;
+            @Nullable String country = null;
+            if (paramTerritory != null) {
+                try {
+                    territory = resolveTerritory(StringEscapeUtils.unescapeHtml4(paramTerritory), null);
+                } catch (final IllegalArgumentException ignored) {
+                    throw new ApiInvalidFormatException(PARAM_TERRITORY, paramTerritory, API_ERROR_VALID_TERRITORY_CODES);
+                }
+            } else if (paramCountry != null) {
+                try {
+                    final String countryUnescaped = StringEscapeUtils.unescapeHtml4(paramCountry);
+                    //noinspection NestedTryStatement
+                    try {
+                        Territory.fromCountryISO2(countryUnescaped);
+                        country = countryUnescaped;
+                    } catch (final IllegalArgumentException ignored) {
+                        Territory.fromCountryISO3(countryUnescaped);
+                        country = countryUnescaped;
+                    }
+                } catch (final IllegalArgumentException ignored) {
+                    throw new ApiInvalidFormatException(PARAM_COUNTRY, paramCountry, API_ERROR_VALID_COUNTRY_CODES);
+                }
             }
 
             // Get the alphabet.
@@ -242,7 +266,11 @@ public void convertLatLonToMapcode(
 
                 // Get all mapcodes.
                 final List<Mapcode> mapcodes;
-                mapcodes = MapcodeCodec.encode(latDeg, lonDeg, territory);
+                if (country != null) {
+                    mapcodes = MapcodeCodec.encodeRestrictToCountryISO(latDeg, lonDeg, country);
+                } else {
+                    mapcodes = MapcodeCodec.encode(latDeg, lonDeg, territory);
+                }
                 mapcodes.forEach(mapcode -> {
                     try {
                         final Rectangle rectangle = MapcodeCodec.decodeToRectangle(mapcode.getCode(), mapcode.getTerritory());
@@ -261,10 +289,22 @@ public void convertLatLonToMapcode(
 
                 // Get the shortest local mapcode.
                 Mapcode mapcodeLocal = null;
-                if (territory != null) {
+                if (country != null) {
 
                     // A territory was provided, so simply use first.
-                    mapcodeLocal = MapcodeCodec.encodeToShortest(latDeg, lonDeg, territory);
+                    try {
+                        mapcodeLocal = MapcodeCodec.encodeToShortest(latDeg, lonDeg, Territory.fromCountryISO(country));
+                    } catch (final UnknownMapcodeException ignored) {
+                        mapcodeLocal = null;
+                    }
+                } else if (territory != null) {
+
+                    // A territory was provided, so simply use first.
+                    try {
+                        mapcodeLocal = MapcodeCodec.encodeToShortest(latDeg, lonDeg, territory);
+                    } catch (final UnknownMapcodeException ignored) {
+                        mapcodeLocal = null;
+                    }
                 } else {
 
                     // Get the shortest code.

diff --git a/service/src/main/java/com/mapcode/services/implementation/OnlyJsonResourceImpl.java b/service/src/main/java/com/mapcode/services/implementation/OnlyJsonResourceImpl.java
@@ -64,15 +64,16 @@ public void convertLatLonToMapcodeJson(
             final double paramLonDeg,
             final int paramPrecision,
             @Nullable final String paramTerritory,
+            @Nullable final String paramCountry,
             @Nullable final String paramContextMustBeNull,
             @Nullable final String paramAlphabet,
             @Nonnull final String paramInclude,
             @Nonnull final String paramClient,
             @Nonnull final String paramAllowLog,
             @Suspended @Nonnull final AsyncResponse response)
             throws ApiInvalidFormatException {
-        mapcodeResource.convertLatLonToMapcode(paramLatDeg, paramLonDeg, paramPrecision, paramTerritory, paramContextMustBeNull,
-                paramAlphabet, paramInclude, paramClient, paramAllowLog, response);
+        mapcodeResource.convertLatLonToMapcode(paramLatDeg, paramLonDeg, paramPrecision, paramTerritory, paramCountry,
+                paramContextMustBeNull, paramAlphabet, paramInclude, paramClient, paramAllowLog, response);
     }
 
     @Override
@@ -82,15 +83,16 @@ public void convertLatLonToMapcodeJson(
             @Nullable final String paramType,
             final int paramPrecision,
             @Nullable final String paramTerritory,
+            @Nullable final String paramCountry,
             @Nullable final String paramContextMustBeNull,
             @Nullable final String paramAlphabet,
             @Nonnull final String paramInclude,
             @Nonnull final String paramClient,
             @Nonnull final String paramDebug,
             @Suspended @Nonnull final AsyncResponse response)
             throws ApiInvalidFormatException {
-        mapcodeResource.convertLatLonToMapcode(paramLatDeg, paramLonDeg, paramType, paramPrecision, paramTerritory, paramContextMustBeNull,
-                paramAlphabet, paramInclude, paramClient, paramDebug, response);
+        mapcodeResource.convertLatLonToMapcode(paramLatDeg, paramLonDeg, paramType, paramPrecision, paramTerritory, paramCountry,
+                paramContextMustBeNull, paramAlphabet, paramInclude, paramClient, paramDebug, response);
     }
 
     @Override

diff --git a/service/src/main/java/com/mapcode/services/implementation/OnlyXmlResourceImpl.java b/service/src/main/java/com/mapcode/services/implementation/OnlyXmlResourceImpl.java
@@ -64,15 +64,16 @@ public void convertLatLonToMapcodeXml(
             final double paramLonDeg,
             final int paramPrecision,
             @Nullable final String paramTerritory,
+            @Nullable final String paramCountry,
             @Nullable final String paramContextMustBeNull,
             @Nullable final String paramAlphabet,
             @Nonnull final String paramInclude,
             @Nonnull final String paramClient,
             @Nonnull final String paramAllowLog,
             @Suspended @Nonnull final AsyncResponse response)
             throws ApiInvalidFormatException {
-        mapcodeResource.convertLatLonToMapcode(paramLatDeg, paramLonDeg, paramPrecision, paramTerritory, paramContextMustBeNull,
-                paramAlphabet, paramInclude, paramClient, paramAllowLog, response);
+        mapcodeResource.convertLatLonToMapcode(paramLatDeg, paramLonDeg, paramPrecision, paramTerritory, paramCountry,
+                paramContextMustBeNull, paramAlphabet, paramInclude, paramClient, paramAllowLog, response);
     }
 
     @Override
@@ -82,15 +83,16 @@ public void convertLatLonToMapcodeXml(
             @Nullable final String paramType,
             final int paramPrecision,
             @Nullable final String paramTerritory,
+            @Nullable final String paramCountry,
             @Nullable final String paramContextMustBeNull,
             @Nullable final String paramAlphabet,
             @Nonnull final String paramInclude,
             @Nonnull final String paramClient,
             @Nonnull final String paramDebug,
             @Suspended @Nonnull final AsyncResponse response)
             throws ApiInvalidFormatException {
-        mapcodeResource.convertLatLonToMapcode(paramLatDeg, paramLonDeg, paramType, paramPrecision, paramTerritory, paramContextMustBeNull,
-                paramAlphabet, paramInclude, paramClient, paramDebug, response);
+        mapcodeResource.convertLatLonToMapcode(paramLatDeg, paramLonDeg, paramType, paramPrecision, paramTerritory, paramCountry,
+                paramContextMustBeNull, paramAlphabet, paramInclude, paramClient, paramDebug, response);
     }
 
     @Override