feat: add LocationIQ provider and improve consistency for other provi…

…ders (#16)

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.12.0
+
+* Add LocationIQ provider
+* [Nominatim] Add `countryCodes` to provider options
+* [Nominatim] Add `dedupe` geocode parameter
+* [Nominatim] Replace `type` with `types` (now an array) in geocoded object
+* [Nominatim] Replace `category` with `categories` (now an array) in geocoded object
+* [Mapbox] Replace `geocodingMode` with `source` in provider options
+* [Mapbox] Replace `resultType` with `types` in geocoded object
+* [Mapbox] Replace `locationTypes` with `types` for geocode and geodecode
+* [MapQuest] Replace `openDomain` with `source` in provider options
+* [GoogleMaps] Replace `locationType` with `precision` in geocoded object
+* [GoogleMaps] Replace `resultType` with `types` in geocoded object
+* [GoogleMaps] Replace `locationTypes` with `precisions` for geodecode
+* [GoogleMaps] Replace `resultTypes` with `types` for geodecode
+* [Yandex] Replace `locationType` with `types` (now an array) in geocoded object
+* [Yandex] Replace `locationTypes` with `types` for geodecode
+
 ## 0.11.1
 
 * Module is side-effect free

README.md

@@ -222,6 +222,13 @@ The following table summarizes the features of each:
       <td>✅️ yes</td>
       <td>❌️ no</td>
     </tr>
+    <tr>
+      <td>LocationIQ</td>
+      <td>locationiq</td>
+      <td>✅️ yes</td>
+      <td>✅️ yes</td>
+      <td>❌️ no</td>
+    </tr>
     <tr>
       <td>Mapbox</td>
       <td>mapbox</td>

couscous.yml

@@ -35,6 +35,9 @@ menu:
         googlemaps:
           text: 📌️ Google Maps (Geocoding API)
           relativeUrl: docs/provider_usage/googlemaps.html
+        locationiq:
+          text: 📌️ LocationIQ
+          relativeUrl: docs/provider_usage/locationiq.html
         mapbox:
           text: 📌️ Mapbox
           relativeUrl: docs/provider_usage/mapbox.html

docs/provider_usage.md

@@ -6,6 +6,7 @@ Each provider has its own options, parameters or results because of its specific
 - [OpenStreetMap (Nominatim)](provider_usage/nominatim.md)
 - [OpenCage](provider_usage/opencage.md)
 - [Google Maps (Geocoding API)](provider_usage/googlemaps.md)
+- [LocationIQ](provider_usage/locationiq.md)
 - [Mapbox](provider_usage/mapbox.md)
 - [MapQuest](provider_usage/mapquest.md)
 - [Bing Maps](provider_usage/bing.md)
@@ -28,7 +29,7 @@ Here is a table listing the parameters according to the providers:
       <td>option</td>
       <td>countryCodes</td>
       <td>Restrict the results to one or more countries</td>
-      <td>Google Maps, Mapbox, OpenCage</td>
+      <td>Google Maps, LocationIQ, Mapbox, Nominatim, OpenCage</td>
     </tr>
     <tr>
       <td>option</td>
@@ -50,15 +51,9 @@ Here is a table listing the parameters according to the providers:
     </tr>
     <tr>
       <td>option</td>
-      <td>geocodingMode</td>
-      <td>Geocoding mode to use</td>
-      <td>Mapbox</td>
-    </tr>
-    <tr>
-      <td>option</td>
-      <td>openDomain</td>
-      <td>To use the Open Geocoding API</td>
-      <td>MapQuest</td>
+      <td>source</td>
+      <td>Source to use</td>
+      <td>LocationIQ, Mapbox, MapQuest</td>
     </tr>
     <tr>
       <td>option</td>
@@ -82,13 +77,13 @@ Here is a table listing the parameters according to the providers:
       <td>geocode</td>
       <td>countryCodes</td>
       <td>Restrict the results to one or more countries</td>
-      <td>Google Maps, Mapbox, Nominatim, OpenCage</td>
+      <td>Google Maps, LocationIQ, Mapbox, Nominatim, OpenCage</td>
     </tr>
     <tr>
       <td>geocode</td>
       <td>bounded</td>
       <td>Restrict the results to items within the bounds</td>
-      <td>Nominatim, Yandex</td>
+      <td>LocationIQ, Nominatim, Yandex</td>
     </tr>
     <tr>
       <td>geocode</td>
@@ -122,22 +117,28 @@ Here is a table listing the parameters according to the providers:
     </tr>
     <tr>
       <td>geocode</td>
-      <td>locationTypes</td>
+      <td>types</td>
       <td>Filter the results to a subset of location types</td>
       <td>Mapbox</td>
     </tr>
     <tr>
       <td>geocode</td>
       <td>excludePlaceIds</td>
       <td>For excluding some locations from the results</td>
-      <td>Nominatim</td>
+      <td>LocationIQ, Nominatim</td>
     </tr>
     <tr>
       <td>geocode</td>
       <td>skip</td>
       <td>Number of items to skip in the response</td>
       <td>Yandex</td>
     </tr>
+    <tr>
+      <td>geocode</td>
+      <td>dedupe</td>
+      <td>Remove the duplicates</td>
+      <td>LocationIQ, Nominatim</td>
+    </tr>
     <tr>
       <td>geocode</td>
       <td>noRecord</td>
@@ -164,21 +165,21 @@ Here is a table listing the parameters according to the providers:
     </tr>
     <tr>
       <td>geodecode</td>
-      <td>locationTypes</td>
-      <td>Filter the results by location types</td>
-      <td>Google Maps, Mapbox, Yandex</td>
+      <td>precisions</td>
+      <td>Restrict the results by the given precisions</td>
+      <td>Google Maps</td>
     </tr>
     <tr>
       <td>geodecode</td>
-      <td>resultTypes</td>
-      <td>Filter the results by address types</td>
-      <td>Google Maps</td>
+      <td>types</td>
+      <td>Filter the results by location types</td>
+      <td>Google Maps, Mapbox, Yandex</td>
     </tr>
     <tr>
       <td>geodecode</td>
       <td>zoom</td>
       <td>Level of details required for the address</td>
-      <td>Npminatim</td>
+      <td>LocationIQ, Nominatim</td>
     </tr>
     <tr>
       <td>geodecode</td>
@@ -208,19 +209,31 @@ Here is a table listing the parameters according to the providers:
       <td>geocoded</td>
       <td>attribution</td>
       <td>Credit information</td>
-      <td>Bing, GeoPlugin, MapQuest, Nominatim</td>
+      <td>Bing, GeoPlugin, LocationIQ, MapQuest, Nominatim</td>
     </tr>
     <tr>
       <td>geocoded</td>
       <td>precision</td>
       <td>Quality of the geocoding result</td>
-      <td>Bing, MapQuest, Yandex</td>
+      <td>Bing, Google Maps, LocationIQ, MapQuest, Yandex</td>
     </tr>
     <tr>
       <td>geocoded</td>
       <td>precisionCode</td>
       <td>Quality code of the geocoding result</td>
-      <td>MapQuest</td>
+      <td>LocationIQ, MapQuest</td>
+    </tr>
+    <tr>
+      <td>geocoded</td>
+      <td>precisionType</td>
+      <td>Quality code of the geocoding result</td>
+      <td>LocationIQ</td>
+    </tr>
+    <tr>
+      <td>geocoded</td>
+      <td>distance</td>
+      <td>Distance between the input location and the result location</td>
+      <td>LocationIQ</td>
     </tr>
     <tr>
       <td>geocoded</td>
@@ -232,19 +245,19 @@ Here is a table listing the parameters according to the providers:
       <td>geocoded</td>
       <td>placeId</td>
       <td>Unique identifier for the location</td>
-      <td>Google Maps</td>
+      <td>Google Maps, LocationIQ</td>
     </tr>
     <tr>
       <td>geocoded</td>
       <td>osmId</td>
       <td>Reference to the OpenStreetMap object</td>
-      <td>Nominatim</td>
+      <td>LocationIQ, Nominatim</td>
     </tr>
     <tr>
       <td>geocoded</td>
       <td>osmType</td>
       <td>Reference to the OpenStreetMap object</td>
-      <td>Nominatim</td>
+      <td>LocationIQ, Nominatim</td>
     </tr>
     <tr>
       <td>geocoded</td>
@@ -258,18 +271,6 @@ Here is a table listing the parameters according to the providers:
       <td>Indicate the geocoder did not return an exact match</td>
       <td>Google Maps</td>
     </tr>
-    <tr>
-      <td>geocoded</td>
-      <td>resultType</td>
-      <td>Result types</td>
-      <td>Google Maps, Mapbox</td>
-    </tr>
-    <tr>
-      <td>geocoded</td>
-      <td>locationType</td>
-      <td>Type representing the precision of the result</td>
-      <td>Google Maps, Yandex</td>
-    </tr>
     <tr>
       <td>geocoded</td>
       <td>streetAddress</td>
@@ -280,25 +281,25 @@ Here is a table listing the parameters according to the providers:
       <td>geocoded</td>
       <td>displayName</td>
       <td>Full comma-separated address</td>
-      <td>Google Maps</td>
+      <td>LocationIQ, Nominatim</td>
     </tr>
     <tr>
       <td>geocoded</td>
-      <td>category</td>
-      <td>Category of the location</td>
-      <td>Nominatim</td>
+      <td>categories</td>
+      <td>Categories of the location</td>
+      <td>LocationIQ, Nominatim</td>
     </tr>
     <tr>
       <td>geocoded</td>
-      <td>type</td>
-      <td>Type of the location</td>
-      <td>Nominatim</td>
+      <td>types</td>
+      <td>Types of the location</td>
+      <td>Google Maps, LocationIQ, Mapbox, Nominatim, Yandex</td>
     </tr>
     <tr>
       <td>geocoded</td>
       <td>subLocalityLevels</td>
       <td>Levels for the sublocality</td>
-      <td>Google Maps, Nominatim</td>
+      <td>Google Maps, LocationIQ, Nominatim</td>
     </tr>
     <tr>
       <td>geocoded</td>

docs/provider_usage/googlemaps.md

@@ -14,16 +14,16 @@
 
 ## `geodecode` parameters
 
-- `resultTypes`: to filter the results by address types
-- `locationTypes` (possible values: "ROOFTOP", "RANGE_INTERPOLATED", "GEOMETRIC_CENTER", "APPROXIMATE"): to filter the results by location types
+- `types`: to filter the results by address types
+- `precisions` (possible values: "ROOFTOP", "RANGE_INTERPOLATED", "GEOMETRIC_CENTER", "APPROXIMATE"): to filter the results by precisions
 - `channel`: channel to use for this request (Premium only)
 
 ## `Geocoded` properties
 
 - `placeId`: a unique identifier used with other Google APIs
 - `partialMatch`: to indicate the geocoder did not return an exact match
-- `resultType`: an array of result types
-- `locationType`: a type representing the precision of the result
+- `types`: the result types
+- `precision`: a type representing the precision of the result
 - `streetAddress`: the street number with the street name
 - `intersection`, `political`, `colloquialArea`, `ward`, `neighborhood`, `premise`, `subpremise`, `naturalFeature`, `airport`, `park`, `pointOfInterest`, `establishment`, `postalCodeSuffix`: additional address components
 - `subLocalityLevels`: levels for the sublocality (greater level number means smaller area)

docs/provider_usage/locationiq.md

@@ -0,0 +1,30 @@
+# LocationIQ Usage
+
+## Options
+
+- `countryCodes`: to restrict the results to one or more countries (ISO 3166 alpha 2 country codes)
+- `source` (default: "locationiq"): set it to "nominatim" to have only results from OpenStreetMap data
+
+## `geocode` parameters
+
+- `countryCodes`: to restrict the results to one or more countries (ISO 3166 alpha 2 country codes)
+- `excludePlaceIds`: for excluding some OpenStreetMap objects from the results
+- `bounded` (only if `bounds` is used): boolean to restrict the results to items within the bounds
+- `dedupe`: boolean to remove the duplicates
+
+## `geodecode` parameters
+
+- `zoom` (default: 18, from 0 to 18): the level of details required for the address
+
+## `Geocoded` properties
+
+- `placeId`: an internal identifier
+- `displayName`: full comma-separated address
+- `osmId`, `osmType`: reference to the OpenStreetMap object
+- `categories`: keys of the main OpenStreetMap tag (only one)
+- `types`: values of the main OpenStreetMap tag (only one)
+- `precision`: the most granular address element that matches the geocoding query
+- `precisionCode`: the quality of the returned address
+- `precisionType`: the quality of the returned location match
+- `attribution`: licensing information
+- `subLocalityLevels`: levels for the sublocality (greater level number means smaller area)

docs/provider_usage/mapbox.md

@@ -2,22 +2,22 @@
 
 ## Options
 
-- `geocodingMode` (default: "mapbox.places"): the geocoding mode to use
+- `source` (default: "mapbox.places"): the endpoint to use
 - `countryCodes`: to restrict the results to one or more countries (ISO 3166 alpha 2 country codes)
 
 ## `geocode` parameters
 
 - `countryCodes`: to restrict the results to one or more countries (ISO 3166 alpha 2 country codes)
 - `proximity` (object with `latitude` and `longitude` keys): to bias the response to favor results that are closer to the specified location
 - `fuzzyMatch`: to approximate the request terms or do an exact matching
-- `locationTypes` (possible values: "country", "region", "postcode", "district", "place", "locality", "neighborhood", "address", "poi"): to filter the results to a subset of location types
+- `types` (possible values: "country", "region", "postcode", "district", "place", "locality", "neighborhood", "address", "poi"): to filter the results to a subset of location types
 
 ## `geodecode` parameters
 
 - `countryCodes`: to restrict the results to one or more countries (ISO 3166 alpha 2 country codes)
 - `reverseMode` ("distance" or "score", default: "distance"): how results are sorted
-- `locationTypes` (possible values: "country", "region", "postcode", "district", "place", "locality", "neighborhood", "address", "poi"): to filter the results to a subset of location types
+- `types` (possible values: "country", "region", "postcode", "district", "place", "locality", "neighborhood", "address", "poi"): to filter the results to a subset of location types
 
 ## `Geocoded` properties
 
-- `resultType`: an array of result types
+- `types`: the result types

docs/provider_usage/mapquest.md

@@ -3,7 +3,7 @@
 ## Options
 
 - `method` ("GET" or "POST", default: "GET"): the HTTP method to use when executing the query
-- `openDomain` (default: false): boolean to use the Open Geocoding API (relies solely on data contributed to OpenStreetMap)
+- `source` (default: "mapquest"): set it to "nominatim" to use the Open Geocoding API (relies solely on data contributed to OpenStreetMap)
 
 ## `geocode` parameters
 

docs/provider_usage/nominatim.md

@@ -5,12 +5,14 @@
 - `userAgent` (required if default host): a User-Agent identifying your application is needed to use Nominatim (see https://operations.osmfoundation.org/policies/nominatim/)
 - `referer`: if you want to set a Referer as well
 - `host` (default: "nominatim.openstreetmap.org"): to use another host
+- `countryCodes`: to restrict the results to one or more countries (ISO 3166 alpha 2 country codes)
 
 ## `geocode` parameters
 
 - `countryCodes`: to restrict the results to one or more countries (ISO 3166 alpha 2 country codes)
 - `excludePlaceIds`: for excluding some OpenStreetMap objects from the results
 - `bounded` (only if `bounds` is used): boolean to restrict the results to items within the bounds
+- `dedupe`: boolean to remove the duplicates
 
 ## `geodecode` parameters
 
@@ -20,6 +22,7 @@
 
 - `displayName`: full comma-separated address
 - `osmId`, `osmType`: reference to the OpenStreetMap object
-- `category`, `type`: key and value of the main OpenStreetMap tag
+- `categories`: keys of the main OpenStreetMap tag (only one)
+- `types`: values of the main OpenStreetMap tag (only one)
 - `attribution`: OpenStreetMap licensing information
 - `subLocalityLevels`: levels for the sublocality (greater level number means smaller area)

docs/provider_usage/yandex.md

@@ -9,10 +9,10 @@
 
 ## `geodecode` parameters
 
-- `locationTypes` (possible values: "house", "street", "metro", "district", "locality", ...): to filter the results by location types
+- `types` (possible values: "house", "street", "metro", "district", "locality", ...): to filter the results by location types
 - `skip`: the number of items to skip in the response
 
 ## `Geocoded` properties
 
-- `locationType`: the type of location
+- `types`: the types of location (only one)
 - `precision`: the quality of the geocoding result