mapricot-api 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85ceb14ed10d1d3499221e1e2f4378cd3e40c58b4b3274e341004452bc873518
-  data.tar.gz: 3a01af9ed6d7431e07255bb635e09d77dd01232c613b9a469da9815d601cd659
+  metadata.gz: a4ab17244df7dcde59e10619f66ad46c84678daaead1900996dc8a284500e8f8
+  data.tar.gz: 7b39f91e9e319ce5caa5600ab88bf5af044ad5749f3c114b8f9198535dcf918d
 SHA512:
-  metadata.gz: 46a943e94e0f8c2d0d22ddb9d1f7857034b6599fa87633ddbf3d71b982172abf70f096edfbf560b139a0f7a00708d0ef8f5c9a85e2bd97671ec7268c391f8eb1
-  data.tar.gz: e5d5becbf5f3de0301f40963ef84317efde3f606ebca3a90050a2c2e98ec23ba3d631e54274f5f3c97fd0aeda837a9a69328bec76c2ff5c872152b1347f98779
+  metadata.gz: fd4c75fbb3ef76fe024d05639c0f6173c8916a920529d551fbd60023da3b40b26bed1efa2b4c9db9620654ecdde982cbf3b4e537fa74ca033da17649f5fb5d27
+  data.tar.gz: 80479d041ae94f4aed582895c778aff3e52979cc12742934ecdbabb2123599e22fea02c8bb7a7aae99e0e0b78f177db588ce632c40c4e5c40842a3f4be722aed

data/README.md

@@ -29,11 +29,13 @@ Methods are grouped by product, the same way as the API's paths. Each returns th
 | Method | Endpoint |
 | --- | --- |
 | `client.geocoding.search(q, focus:, country:, limit:, lang:)` | [`GET /geocoding/v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
+| `client.geocoding.search_batch(queries)` | [`POST /geocoding/v1/search/batch`](https://mapricot.com/docs/geocoding/#search-a-list-of-addresses) |
 | `client.geocoding.autocomplete(q, focus:, country:, limit:, lang:)` | [`GET /geocoding/v1/autocomplete`](https://mapricot.com/docs/geocoding/#suggest-as-people-type) |
 | `client.geocoding.reverse(lat, lon, limit:, lang:)` | [`GET /geocoding/v1/reverse`](https://mapricot.com/docs/geocoding/#find-the-address-at-a-point) |
 | `client.places.nearby(lat, lon, category:, radius:, limit:, lang:)` | [`GET /places/v1/nearby`](https://mapricot.com/docs/places/#list-places-around-a-point) |
 | `client.places.get(id, lang:)` | [`GET /places/v1/{id}`](https://mapricot.com/docs/places/#look-up-a-saved-place) |
 | `client.routing.route(waypoints, mode:, geometries:, steps:, lang:)` | [`POST /routing/v1/route`](https://mapricot.com/docs/routing/#get-a-route) |
+| `client.routing.optimize(waypoints, mode:, geometries:, steps:, lang:)` | [`POST /routing/v1/optimize`](https://mapricot.com/docs/routing/#optimize-the-order-of-stops) |
 | `client.routing.isochrone(location, minutes, mode:)` | [`POST /routing/v1/isochrone`](https://mapricot.com/docs/routing/#get-an-isochrone) |
 | `client.ip_geolocation.lookup(ip)` | [`GET /ip-geolocation/v1/{ip}`](https://mapricot.com/docs/ip-geolocation/#look-up-an-address) |
 | `client.account` | `GET /account`, which checks a key and is never billed |
@@ -46,10 +48,19 @@ route = client.routing.route([{ lat: 45.5189, lon: -122.6793 }, { lat: 45.5214,
 puts route["routes"][0]["durationSeconds"]
 ```
 
+`search_batch` runs up to 100 searches in one request. Each query is a Hash of `search`'s parameters, and `"responses"` answers them in the same order, each with `"results"` and `"attribution"`, or an `"error"` with the `"code"` and `"message"` that search would get, without raising. Each completed search is billed as one request; errors aren't.
+
+```ruby
+batch = client.geocoding.search_batch([{ q: "128 SW 3rd Ave, Portland", limit: 1 }, { q: "10 Downing Street, London", limit: 1 }])
+batch["responses"].each { |response| puts response.dig("error", "message") || response["results"][0]["label"] }
+```
+
 A route's path comes as an encoded `polyline` with five decimal places, which polyline decoders assume. Pass `geometries: "geojson"` to get it as a GeoJSON `LineString` in `geometry` instead, which maps draw without decoding, or `geometries: "polyline6"` for six decimal places.
 
 Pass `steps: true` and each leg's `steps` has its turn-by-turn directions: an `instruction`, its distance and time, and its `lat` and `lon`. They're in English unless you pass `lang`, such as `lang: "fr"`.
 
+`routing.optimize` takes the same arguments as `routing.route` and returns the route that visits the waypoints in a fast order, keeping the first and last in place. It adds `"waypointOrder"`: the indexes of your waypoints in visiting order, which `"legs"` follow. Every pair of waypoints must be within 400 km of each other for `drive`, or 200 km for `walk` and `bicycle`.
+
 An isochrone is a GeoJSON `FeatureCollection` with one polygon per time, largest first, so a map that draws them in order shows the smaller ones on top:
 
 ```ruby

data/lib/mapricot/api.rb

@@ -7,7 +7,7 @@ require "net/http"
 # The official client for the Mapricot API: address and place search, reverse geocoding, nearby places, routing,
 # and IP geolocation. See https://mapricot.com/docs/ruby/.
 module Mapricot
-  VERSION = "0.7.0"
+  VERSION = "0.9.0"
 
   # An error response from the API.
   class Error < StandardError
@@ -33,7 +33,7 @@ module Mapricot
       @base_url = base_url
       @timeout = timeout
       @max_retries = max_retries
-      @geocoding = GeocodingService.new(method(:get))
+      @geocoding = GeocodingService.new(method(:get), method(:post), method(:query_value))
       @places = PlacesService.new(method(:get))
       @routing = RoutingService.new(method(:post))
       @ip_geolocation = IpGeolocationService.new(method(:get))
@@ -104,8 +104,10 @@ module Mapricot
 
   # client.geocoding: the /geocoding/v1 endpoints.
   class GeocodingService
-    def initialize(get)
+    def initialize(get, post, query_value)
       @get = get
+      @post = post
+      @query_value = query_value
     end
 
     # Find addresses and places matching free text. focus is {lat:, lon:}; country is an Array or a String.
@@ -113,6 +115,14 @@ module Mapricot
       @get.call("/geocoding/v1/search", q: q, focus: focus, country: country, limit: limit, lang: lang)
     end
 
+    # Run up to 100 searches in one request, each a Hash of search's parameters, as in { q: "…", limit: 1 }. Each
+    # completed search is billed as one request. "responses" answers them in order, each with "results" and
+    # "attribution", or an "error" with the code and message the search would get on its own, which isn't raised.
+    def search_batch(queries)
+      body = { queries: queries.map { |query| query.compact.transform_values { |value| @query_value.call(value) } } }
+      @post.call("/geocoding/v1/search/batch", body)
+    end
+
     # Suggest addresses and places as someone types.
     def autocomplete(q, focus: nil, country: nil, limit: nil, lang: nil)
       @get.call("/geocoding/v1/autocomplete", q: q, focus: focus, country: country, limit: limit, lang: lang)
@@ -155,6 +165,14 @@ module Mapricot
       @post.call("/routing/v1/route", body)
     end
 
+    # Find a fast route through 2 to 20 waypoints, keeping the first and last in place and reordering the rest. It
+    # takes the same arguments as route, and the route adds "waypointOrder": the indexes of the waypoints sent, in
+    # visiting order.
+    def optimize(waypoints, mode: nil, geometries: nil, steps: nil, lang: nil)
+      body = { waypoints: waypoints, mode: mode, geometries: geometries, steps: steps, lang: lang }
+      @post.call("/routing/v1/optimize", body)
+    end
+
     # The areas reachable from a location, {lat:, lon:}, within 1 to 4 times, each 1 to 60 minutes, as a GeoJSON
     # FeatureCollection with one polygon per time, largest first. mode is as for route.
     def isochrone(location, minutes, mode: nil)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mapricot-api
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Mapricot