mapricot-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31d656521ae328f37c56e40ebc8be88f9dcfb2157c530df0af8506239f0926bc
+  data.tar.gz: 947d9768c032efb16d615f0d662636006376dc0935164d0f357fbebbc61d7f18
+SHA512:
+  metadata.gz: b797cf979be35da5c8bcdcf14262e8b989b85e61718c2154bee7e20d1e1644bf14f03da1c8ded58821c457f1983c53df7911517f0c2664902171418bc9f1aca8
+  data.tar.gz: 2687accc178bff6578f19d3f45abeb42749c69c84d623f18a84eae2050c342297b60bb3a32bfeafdd741c7240718de4a9112462b7dc226e9e4f660a3992ce4fb

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mapricot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+# Mapricot for Ruby
+
+The official Ruby client for the [Mapricot API](https://mapricot.com/): address and place search, reverse geocoding, nearby places, routing, and IP geolocation, with 250,000 free requests every month.
+
+```sh
+gem install mapricot-api
+```
+
+It needs Ruby 3.1 or later and has no dependencies outside the standard library.
+
+## Quick start
+
+Create a server key in the [dashboard](https://app.mapricot.com/) and set it as `MAPRICOT_KEY`:
+
+```sh
+export MAPRICOT_KEY="mapricot_sk_…"
+```
+
+```ruby
+require "mapricot/api"
+
+client = Mapricot::Client.new
+
+data = client.search("128 SW 3rd Ave, Portland", limit: 1)
+place = data["results"][0]
+puts place["label"], place["lat"], place["lon"]
+```
+
+Pass the key yourself with `Mapricot::Client.new(api_key: "mapricot_sk_…")`.
+
+## 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/).
+
+| Method | Endpoint |
+| --- | --- |
+| `client.search(q, focus:, country:, limit:, lang:)` | [`GET /v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
+| `client.autocomplete(q, focus:, country:, limit:, lang:)` | [`GET /v1/autocomplete`](https://mapricot.com/docs/places/#suggest-as-people-type) |
+| `client.reverse(lat, lon, limit:, lang:)` | [`GET /v1/reverse`](https://mapricot.com/docs/geocoding/#find-the-address-at-a-point) |
+| `client.nearby(lat, lon, category:, radius:, limit:, lang:)` | [`GET /v1/nearby`](https://mapricot.com/docs/places/#list-places-around-a-point) |
+| `client.place(id, lang:)` | [`GET /v1/places/{id}`](https://mapricot.com/docs/places/#look-up-a-saved-place) |
+| `client.route(waypoints, mode:)` | [`POST /v1/route`](https://mapricot.com/docs/routing/#get-a-route) |
+| `client.ip(address)` | [`GET /v1/ip/{ip}`](https://mapricot.com/docs/ip-geolocation/#look-up-an-address) |
+| `client.account` | `GET /v1/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")
+puts route["routes"][0]["durationSeconds"]
+```
+
+A route's `polyline` is encoded with six decimal places. Decode it with precision 6, as [decoding a route polyline](https://mapricot.com/docs/polyline/) shows.
+
+If your app shows results, show the credits in each response's `attribution`.
+
+## Errors and retries
+
+An error response raises `Mapricot::Error`, with the HTTP `status`, the API's error `code`, a `message`, and the `request_id`:
+
+```ruby
+begin
+  client.search("")
+rescue Mapricot::Error => e
+  puts e.status, e.code, e.message # 400, invalid_request, The service rejected the request.
+end
+```
+
+The client retries `503` responses and `429 concurrency_exceeded`, up to twice, waiting longer each time. Errors aren't billed. Pass `max_retries:` and `timeout:` (seconds) to `Mapricot::Client.new` to change this. The [API reference](https://mapricot.com/api-reference/#errors) lists every status.
+
+## Links
+
+- [Mapricot](https://mapricot.com/)
+- [Ruby docs](https://mapricot.com/docs/ruby/)
+- [API reference](https://mapricot.com/api-reference/)
+- [Pricing](https://mapricot.com/pricing/)

data/lib/mapricot/api.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+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.1.0"
+
+  # An error response from the API.
+  class Error < StandardError
+    attr_reader :status, :code, :request_id
+
+    def initialize(status, code, message, request_id)
+      super(message)
+      @status = status
+      @code = code
+      @request_id = request_id
+    end
+  end
+
+  # Each method returns the API's JSON as a Hash with string keys, as in https://mapricot.com/api-reference/.
+  class Client
+    def initialize(api_key: ENV["MAPRICOT_KEY"], base_url: "https://api.mapricot.com", timeout: 30, max_retries: 2)
+      raise ArgumentError, "Pass api_key: or set MAPRICOT_KEY." if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @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("/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("/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("/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("/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("/v1/places/#{escape(id)}", lang: lang)
+    end
+
+    # Find a route through 2 to 20 waypoints, each {lat:, lon:}. mode is "drive" (the default), "walk", or "bicycle".
+    def route(waypoints, mode: nil)
+      body = { waypoints: waypoints, mode: mode }.compact
+      request(Net::HTTP::Post, URI("#{@base_url}/v1/route"), JSON.generate(body))
+    end
+
+    # Approximate location of a public IP address.
+    def ip(address)
+      get("/v1/ip/#{escape(address)}")
+    end
+
+    # The key's account. Not billed, so it checks a key for free.
+    def account
+      get("/v1/account")
+    end
+
+    private
+
+    def get(path, **params)
+      uri = URI(@base_url + path)
+      query = params.compact.transform_values { |value| query_value(value) }
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      request(Net::HTTP::Get, uri)
+    end
+
+    def request(method, uri, body = nil)
+      attempt = 0
+      loop do
+        req = method.new(uri)
+        req["Authorization"] = "Bearer #{@api_key}"
+        req["User-Agent"] = "mapricot-ruby/#{VERSION}"
+        if body
+          req["Content-Type"] = "application/json"
+          req.body = body
+        end
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                       open_timeout: @timeout, read_timeout: @timeout) do |http|
+          http.request(req)
+        end
+        return JSON.parse(response.body) if response.is_a?(Net::HTTPOK)
+
+        error = error_from(response)
+        raise error if attempt >= @max_retries || !retryable?(error)
+
+        sleep(0.5 * 2**attempt)
+        attempt += 1
+      end
+    end
+
+    def query_value(value)
+      case value
+      when Hash then "#{value.fetch(:lat)},#{value.fetch(:lon)}"
+      when Array then value.join(",")
+      else value.to_s
+      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")
+      Error.new(response.code.to_i, error.fetch("code"), error.fetch("message"), request_id)
+    rescue JSON::ParserError, KeyError, TypeError
+      Error.new(response.code.to_i, "unknown", "HTTP #{response.code}", request_id)
+    end
+
+    def retryable?(error)
+      error.status == 503 || error.code == "concurrency_exceeded"
+    end
+  end
+end

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: mapricot-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mapricot
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mapricot/api.rb
+homepage: https://mapricot.com/
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://mapricot.com/docs/ruby/
+  source_code_uri: https://github.com/mapricothq/mapricot-ruby
+  bug_tracker_uri: https://github.com/mapricothq/mapricot-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Official client for the Mapricot API: geocoding, places, routing, and IP
+  geolocation.'
+test_files: []