mapricot-api 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +15 -7
- data/lib/mapricot/api.rb +14 -9
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 9bc321819cc79bc1fa54ad0ea299a93c1e21362e25bf79c524f26af234ec1577
|
|
4
|
+
data.tar.gz: c0b7c20c95f41df1e2fdc85a3079eddfee2e8f1c46b2ac9b3672f1174f5c8651
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 429d97f2c96011452f19181d7335324735c4c7dbd7bc0cf50745e80c1552d3599efa05c1b91be66fe30f28bb0cc4bceca3e87d8f49daeeff8b0f13d113203c35
|
|
7
|
+
data.tar.gz: 39fedf7b581ada641578873f6048003e39ca82ce95a606c615be5c004017fa981ae26ac14644b5ba3126802a0d9e28904debda82c77810d4ed70c9839f7e1ef7
|
data/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Mapricot for Ruby
|
|
2
2
|
|
|
3
|
-
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
|
|
3
|
+
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 30 days.
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
6
|
gem install mapricot-api
|
|
@@ -24,11 +24,11 @@ puts place["label"], place["lat"], place["lon"]
|
|
|
24
24
|
|
|
25
25
|
## Methods
|
|
26
26
|
|
|
27
|
-
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/).
|
|
27
|
+
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/docs/api-reference/).
|
|
28
28
|
|
|
29
29
|
| Method | Endpoint |
|
|
30
30
|
| --- | --- |
|
|
31
|
-
| `client.geocoding.search(q, focus:, country:, limit:, lang:)` | [`GET /geocoding/v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
|
|
31
|
+
| `client.geocoding.search(q, address:, locality:, county:, region:, postal_code:, focus:, country:, limit:, lang:)` | [`GET /geocoding/v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
|
|
32
32
|
| `client.geocoding.search_batch(queries)` | [`POST /geocoding/v1/search/batch`](https://mapricot.com/docs/geocoding/#search-a-list-of-addresses) |
|
|
33
33
|
| `client.geocoding.autocomplete(q, focus:, country:, limit:, lang:)` | [`GET /geocoding/v1/autocomplete`](https://mapricot.com/docs/geocoding/#suggest-as-people-type) |
|
|
34
34
|
| `client.geocoding.reverse(lat, lon, limit:, lang:)` | [`GET /geocoding/v1/reverse`](https://mapricot.com/docs/geocoding/#find-the-address-at-a-point) |
|
|
@@ -36,7 +36,7 @@ Methods are grouped by product, the same way as the API's paths. Each returns th
|
|
|
36
36
|
| `client.places.get(id, lang:)` | [`GET /places/v1/{id}`](https://mapricot.com/docs/places/#look-up-a-saved-place) |
|
|
37
37
|
| `client.routing.route(waypoints, mode:, geometries:, steps:, lang:, costing:)` | [`POST /routing/v1/route`](https://mapricot.com/docs/routing/#get-a-route) |
|
|
38
38
|
| `client.routing.optimize(waypoints, mode:, geometries:, steps:, lang:, costing:)` | [`POST /routing/v1/optimize`](https://mapricot.com/docs/routing/#optimize-the-order-of-stops) |
|
|
39
|
-
| `client.routing.isochrone(location, minutes, mode:, costing:)` | [`POST /routing/v1/isochrone`](https://mapricot.com/docs/routing/#get-an-isochrone) |
|
|
39
|
+
| `client.routing.isochrone(location, minutes, mode:, costing:, generalize:)` | [`POST /routing/v1/isochrone`](https://mapricot.com/docs/routing/#get-an-isochrone) |
|
|
40
40
|
| `client.ip_geolocation.lookup(ip)` | [`GET /ip-geolocation/v1/{ip}`](https://mapricot.com/docs/ip-geolocation/#look-up-an-address) |
|
|
41
41
|
| `client.account` | `GET /account`, which checks a key and is never billed |
|
|
42
42
|
|
|
@@ -48,7 +48,13 @@ route = client.routing.route([{ lat: 45.5189, lon: -122.6793 }, { lat: 45.5214,
|
|
|
48
48
|
puts route["routes"][0]["durationSeconds"]
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
|
|
51
|
+
When you already have an address in parts, such as a spreadsheet's columns, pass them in place of `q`. Search ignores a blank part:
|
|
52
|
+
|
|
53
|
+
```ruby
|
|
54
|
+
data = client.geocoding.search(address: "10 Downing Street", locality: "London", postal_code: "SW1A 2AA", country: "GB")
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`search_batch` runs up to 100 searches in one request. Each query is a Hash of `search`'s parameters, with `q` or the address parts named as in the API, such as `postalCode`, 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.
|
|
52
58
|
|
|
53
59
|
```ruby
|
|
54
60
|
batch = client.geocoding.search_batch([{ q: "128 SW 3rd Ave, Portland", limit: 1 }, { q: "10 Downing Street, London", limit: 1 }])
|
|
@@ -70,6 +76,8 @@ area = client.routing.isochrone({ lat: 45.5189, lon: -122.6793 }, [5, 10], mode:
|
|
|
70
76
|
puts area["features"].map { |feature| feature["properties"]["minutes"] }.inspect
|
|
71
77
|
```
|
|
72
78
|
|
|
79
|
+
`generalize` smooths each outline to within that many meters, from 10 to 5000, so it has fewer points. The API picks it from the travel time when you leave it out. A long drive's outlines are detailed and large, and `generalize: 300` makes them much smaller while keeping their shape at city scale.
|
|
80
|
+
|
|
73
81
|
If your app shows results, show the credits in each response's `attribution`.
|
|
74
82
|
|
|
75
83
|
## Errors and retries
|
|
@@ -84,11 +92,11 @@ rescue Mapricot::Error => e
|
|
|
84
92
|
end
|
|
85
93
|
```
|
|
86
94
|
|
|
87
|
-
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.
|
|
95
|
+
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/docs/api-reference/#errors) lists every status.
|
|
88
96
|
|
|
89
97
|
## Links
|
|
90
98
|
|
|
91
99
|
- [Mapricot](https://mapricot.com/)
|
|
92
100
|
- [Ruby docs](https://mapricot.com/docs/ruby/)
|
|
93
|
-
- [API reference](https://mapricot.com/api-reference/)
|
|
101
|
+
- [API reference](https://mapricot.com/docs/api-reference/)
|
|
94
102
|
- [Pricing](https://mapricot.com/pricing/)
|
data/lib/mapricot/api.rb
CHANGED
|
@@ -7,7 +7,7 @@ require "net/http"
|
|
|
7
7
|
# The official client for the Mapricot API: address and place search, reverse geocoding, nearby places, routing,
|
|
8
8
|
# and IP geolocation. See https://mapricot.com/docs/ruby/.
|
|
9
9
|
module Mapricot
|
|
10
|
-
VERSION = "0.
|
|
10
|
+
VERSION = "0.12.0"
|
|
11
11
|
|
|
12
12
|
# An error response from the API.
|
|
13
13
|
class Error < StandardError
|
|
@@ -22,7 +22,7 @@ module Mapricot
|
|
|
22
22
|
end
|
|
23
23
|
|
|
24
24
|
# Methods are grouped by product, as in client.geocoding.search. Each returns the API's JSON as a Hash with string
|
|
25
|
-
# keys, as in https://mapricot.com/api-reference/.
|
|
25
|
+
# keys, as in https://mapricot.com/docs/api-reference/.
|
|
26
26
|
class Client
|
|
27
27
|
attr_reader :geocoding, :places, :routing, :ip_geolocation
|
|
28
28
|
|
|
@@ -110,12 +110,16 @@ module Mapricot
|
|
|
110
110
|
@query_value = query_value
|
|
111
111
|
end
|
|
112
112
|
|
|
113
|
-
# Find addresses and places matching free text
|
|
114
|
-
|
|
115
|
-
|
|
113
|
+
# Find addresses and places matching free text in q, or an address given in parts in place of q, as in
|
|
114
|
+
# search(address: "10 Downing Street", locality: "London"). focus is {lat:, lon:}; country is an Array or a String.
|
|
115
|
+
def search(q = nil, address: nil, locality: nil, county: nil, region: nil, postal_code: nil, focus: nil, country: nil,
|
|
116
|
+
limit: nil, lang: nil)
|
|
117
|
+
@get.call("/geocoding/v1/search", q: q, address: address, locality: locality, county: county, region: region,
|
|
118
|
+
postalCode: postal_code, focus: focus, country: country, limit: limit, lang: lang)
|
|
116
119
|
end
|
|
117
120
|
|
|
118
|
-
# Run up to 100 searches in one request, each a Hash of search's parameters, as in { q: "…", limit: 1 }
|
|
121
|
+
# Run up to 100 searches in one request, each a Hash of search's parameters, as in { q: "…", limit: 1 } or
|
|
122
|
+
# { address: "…", postalCode: "…" }, with the API's names. Each
|
|
119
123
|
# completed search is billed as one request. "responses" answers them in order, each with "results" and
|
|
120
124
|
# "attribution", or an "error" with the code and message the search would get on its own, which isn't raised.
|
|
121
125
|
def search_batch(queries)
|
|
@@ -175,9 +179,10 @@ module Mapricot
|
|
|
175
179
|
end
|
|
176
180
|
|
|
177
181
|
# The areas reachable from a location, {lat:, lon:}, within 1 to 4 times, each 1 to 60 minutes, as a GeoJSON
|
|
178
|
-
# FeatureCollection with one polygon per time, largest first. mode and costing are as for route.
|
|
179
|
-
|
|
180
|
-
|
|
182
|
+
# FeatureCollection with one polygon per time, largest first. mode and costing are as for route. generalize smooths
|
|
183
|
+
# each outline to within that many meters, from 10 to 5000; left out, the API picks it from the travel time.
|
|
184
|
+
def isochrone(location, minutes, mode: nil, costing: nil, generalize: nil)
|
|
185
|
+
@post.call("/routing/v1/isochrone", { location: location, minutes: minutes, mode: mode, costing: costing, generalize: generalize })
|
|
181
186
|
end
|
|
182
187
|
end
|
|
183
188
|
|