mapricot-api 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24849159506d71db67b1e674bf3cf9377f218c78260002730a2f1dab55b713f9
-  data.tar.gz: '07499083f22bd04f51f65704bb24e204c0f7767564e84de4f92114c6836aa09e'
+  metadata.gz: 85ceb14ed10d1d3499221e1e2f4378cd3e40c58b4b3274e341004452bc873518
+  data.tar.gz: 3a01af9ed6d7431e07255bb635e09d77dd01232c613b9a469da9815d601cd659
 SHA512:
-  metadata.gz: 1b921d6fabb89653dbde12a181390f618e547dada82ea5587108d2e0acc069d8b43e1c427d30d96cf1abe2807933b670462f779aebe4e4499b0b20c23a045b13
-  data.tar.gz: e1f406517e97e473fcc7eece8890e609d26c2921523cb88e18c23f72bc84258d553e540b9e9724d883b057722c6137fd79327b04e75fb72b5d331de1e569dc88
+  metadata.gz: 46a943e94e0f8c2d0d22ddb9d1f7857034b6599fa87633ddbf3d71b982172abf70f096edfbf560b139a0f7a00708d0ef8f5c9a85e2bd97671ec7268c391f8eb1
+  data.tar.gz: e5d5becbf5f3de0301f40963ef84317efde3f606ebca3a90050a2c2e98ec23ba3d631e54274f5f3c97fd0aeda837a9a69328bec76c2ff5c872152b1347f98779

data/README.md

@@ -17,41 +17,43 @@ require "mapricot/api"
 
 client = Mapricot::Client.new(api_key: ENV.fetch("MAPRICOT_KEY"))
 
-data = client.search("128 SW 3rd Ave, Portland", limit: 1)
+data = client.geocoding.search("128 SW 3rd Ave, Portland", limit: 1)
 place = data["results"][0]
 puts place["label"], place["lat"], place["lon"]
 ```
 
 ## Methods
 
-Each method returns the API's JSON as a Hash with string keys, with the same field names as the [API reference](https://mapricot.com/api-reference/).
+Methods are grouped by product, the same way as the API's paths. Each returns the API's JSON as a Hash with string keys, with the same field names as the [API reference](https://mapricot.com/api-reference/).
 
 | Method | Endpoint |
 | --- | --- |
-| `client.search(q, focus:, country:, limit:, lang:)` | [`GET /geocoding/v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
-| `client.autocomplete(q, focus:, country:, limit:, lang:)` | [`GET /geocoding/v1/autocomplete`](https://mapricot.com/docs/geocoding/#suggest-as-people-type) |
-| `client.reverse(lat, lon, limit:, lang:)` | [`GET /geocoding/v1/reverse`](https://mapricot.com/docs/geocoding/#find-the-address-at-a-point) |
-| `client.nearby(lat, lon, category:, radius:, limit:, lang:)` | [`GET /places/v1/nearby`](https://mapricot.com/docs/places/#list-places-around-a-point) |
-| `client.place(id, lang:)` | [`GET /places/v1/{id}`](https://mapricot.com/docs/places/#look-up-a-saved-place) |
-| `client.route(waypoints, mode:, geometries:)` | [`POST /routing/v1/route`](https://mapricot.com/docs/routing/#get-a-route) |
-| `client.isochrone(location, minutes, mode:)` | [`POST /routing/v1/isochrone`](https://mapricot.com/docs/routing/#get-an-isochrone) |
-| `client.ip(address)` | [`GET /ip-geolocation/v1/{ip}`](https://mapricot.com/docs/ip-geolocation/#look-up-an-address) |
+| `client.geocoding.search(q, focus:, country:, limit:, lang:)` | [`GET /geocoding/v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
+| `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.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 |
 
 Every keyword argument is optional. `focus` and each waypoint are `{ lat:, lon: }`. `country` and `category` take an Array or a comma-separated String.
 
 ```ruby
-nearby = client.nearby(45.52, -122.68, category: ["food:coffee_shop"], radius: 1000)
-route = client.route([{ lat: 45.5189, lon: -122.6793 }, { lat: 45.5214, lon: -122.6828 }], mode: "walk")
+nearby = client.places.nearby(45.52, -122.68, category: ["food:coffee_shop"], radius: 1000)
+route = client.routing.route([{ lat: 45.5189, lon: -122.6793 }, { lat: 45.5214, lon: -122.6828 }], mode: "walk")
 puts route["routes"][0]["durationSeconds"]
 ```
 
 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"`.
+
 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
-area = client.isochrone({ lat: 45.5189, lon: -122.6793 }, [5, 10], mode: "walk")
+area = client.routing.isochrone({ lat: 45.5189, lon: -122.6793 }, [5, 10], mode: "walk")
 puts area["features"].map { |feature| feature["properties"]["minutes"] }.inspect
 ```
 
@@ -63,7 +65,7 @@ An error response raises `Mapricot::Error`, with the HTTP `status`, the API's er
 
 ```ruby
 begin
-  client.search("")
+  client.geocoding.search("")
 rescue Mapricot::Error => e
   puts e.status, e.code, e.message # 400, invalid_request, The service rejected the request.
 end

data/lib/mapricot/api.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
+require "erb"
 require "json"
 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.5.0"
+  VERSION = "0.7.0"
 
   # An error response from the API.
   class Error < StandardError
@@ -20,8 +21,11 @@ module Mapricot
     end
   end
 
-  # Each method returns the API's JSON as a Hash with string keys, as in https://mapricot.com/api-reference/.
+  # Methods are grouped by product, as in client.geocoding.search. Each returns the API's JSON as a Hash with string
+  # keys, as in https://mapricot.com/api-reference/.
   class Client
+    attr_reader :geocoding, :places, :routing, :ip_geolocation
+
     def initialize(api_key:, base_url: "https://api.mapricot.com", timeout: 30, max_retries: 2)
       raise ArgumentError, "Pass api_key:, a Mapricot key." if api_key.nil? || api_key.empty?
 
@@ -29,50 +33,10 @@ module Mapricot
       @base_url = base_url
       @timeout = timeout
       @max_retries = max_retries
-    end
-
-    # Find addresses and places matching free text. focus is {lat:, lon:}; country is an Array or a String.
-    def search(q, focus: nil, country: nil, limit: nil, lang: nil)
-      get("/geocoding/v1/search", q: q, focus: focus, country: country, limit: limit, lang: lang)
-    end
-
-    # Suggest addresses and places as someone types.
-    def autocomplete(q, focus: nil, country: nil, limit: nil, lang: nil)
-      get("/geocoding/v1/autocomplete", q: q, focus: focus, country: country, limit: limit, lang: lang)
-    end
-
-    # Find the address nearest a coordinate, or the area around it.
-    def reverse(lat, lon, limit: nil, lang: nil)
-      get("/geocoding/v1/reverse", lat: lat, lon: lon, limit: limit, lang: lang)
-    end
-
-    # List places around a coordinate, optionally by category, an Array or a String.
-    def nearby(lat, lon, category: nil, radius: nil, limit: nil, lang: nil)
-      get("/places/v1/nearby", lat: lat, lon: lon, category: category, radius: radius, limit: limit, lang: lang)
-    end
-
-    # Look up one place by its Mapricot ID.
-    def place(id, lang: nil)
-      get("/places/v1/#{escape(id)}", lang: lang)
-    end
-
-    # Find a route through 2 to 20 waypoints, each {lat:, lon:}. mode is "drive" (the default), "walk", or "bicycle".
-    # geometries is "polyline" (the default), "polyline6", or "geojson".
-    def route(waypoints, mode: nil, geometries: nil)
-      body = { waypoints: waypoints, mode: mode, geometries: geometries }.compact
-      request(Net::HTTP::Post, URI("#{@base_url}/routing/v1/route"), JSON.generate(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)
-      body = { location: location, minutes: minutes, mode: mode }.compact
-      request(Net::HTTP::Post, URI("#{@base_url}/routing/v1/isochrone"), JSON.generate(body))
-    end
-
-    # Approximate location of a public IP address.
-    def ip(address)
-      get("/ip-geolocation/v1/#{escape(address)}")
+      @geocoding = GeocodingService.new(method(:get))
+      @places = PlacesService.new(method(:get))
+      @routing = RoutingService.new(method(:post))
+      @ip_geolocation = IpGeolocationService.new(method(:get))
     end
 
     # The key's account. Not billed, so it checks a key for free.
@@ -89,6 +53,10 @@ module Mapricot
       request(Net::HTTP::Get, uri)
     end
 
+    def post(path, body)
+      request(Net::HTTP::Post, URI(@base_url + path), JSON.generate(body.compact))
+    end
+
     def request(method, uri, body = nil)
       attempt = 0
       loop do
@@ -121,10 +89,6 @@ module Mapricot
       end
     end
 
-    def escape(segment)
-      URI.encode_www_form_component(segment).gsub("+", "%20")
-    end
-
     def error_from(response)
       request_id = response["X-Request-Id"]
       error = JSON.parse(response.body).fetch("error")
@@ -137,4 +101,76 @@ module Mapricot
       error.status == 503 || error.code == "concurrency_exceeded"
     end
   end
+
+  # client.geocoding: the /geocoding/v1 endpoints.
+  class GeocodingService
+    def initialize(get)
+      @get = get
+    end
+
+    # Find addresses and places matching free text. focus is {lat:, lon:}; country is an Array or a String.
+    def search(q, focus: nil, country: nil, limit: nil, lang: nil)
+      @get.call("/geocoding/v1/search", q: q, focus: focus, country: country, limit: limit, lang: lang)
+    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)
+    end
+
+    # Find the address nearest a coordinate, or the area around it.
+    def reverse(lat, lon, limit: nil, lang: nil)
+      @get.call("/geocoding/v1/reverse", lat: lat, lon: lon, limit: limit, lang: lang)
+    end
+  end
+
+  # client.places: the /places/v1 endpoints.
+  class PlacesService
+    def initialize(get)
+      @get = get
+    end
+
+    # List places around a coordinate, optionally by category, an Array or a String.
+    def nearby(lat, lon, category: nil, radius: nil, limit: nil, lang: nil)
+      @get.call("/places/v1/nearby", lat: lat, lon: lon, category: category, radius: radius, limit: limit, lang: lang)
+    end
+
+    # Look up one place by its Mapricot ID.
+    def get(id, lang: nil)
+      @get.call("/places/v1/#{ERB::Util.url_encode(id)}", lang: lang)
+    end
+  end
+
+  # client.routing: the /routing/v1 endpoints.
+  class RoutingService
+    def initialize(post)
+      @post = post
+    end
+
+    # Find a route through 2 to 20 waypoints, each {lat:, lon:}. mode is "drive" (the default), "walk", or "bicycle".
+    # geometries is "polyline" (the default), "polyline6", or "geojson". steps: true adds each leg's turn-by-turn
+    # steps, in lang, an ISO 639-1 language, English by default.
+    def route(waypoints, mode: nil, geometries: nil, steps: nil, lang: nil)
+      body = { waypoints: waypoints, mode: mode, geometries: geometries, steps: steps, lang: lang }
+      @post.call("/routing/v1/route", 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)
+      @post.call("/routing/v1/isochrone", { location: location, minutes: minutes, mode: mode })
+    end
+  end
+
+  # client.ip_geolocation: the /ip-geolocation/v1 endpoints.
+  class IpGeolocationService
+    def initialize(get)
+      @get = get
+    end
+
+    # Approximate location of a public IP address.
+    def lookup(ip)
+      @get.call("/ip-geolocation/v1/#{ERB::Util.url_encode(ip)}")
+    end
+  end
 end

metadata

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