my_john_deere_api 2.3.3 → 2.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e82399b62eca7ecbf5c1e1f9d7f0de2391c909bed4426ccafbc19a3b555a2df2
-  data.tar.gz: e38342e0db2b4adc5cc6a9a6bba54b91c7aeb2e56e819a25696fc3c0cde75447
+  metadata.gz: 0b6ea750328ecdcb653d61bbadf19ab4ab23ef2fb712963bda1351736ffedb37
+  data.tar.gz: '059eab2d2bbb7d8d716bde8f61f5ce935c46039dfbe6c82b933041e4f90fd072'
 SHA512:
-  metadata.gz: 2e80cfb7dbd6f7fb209403d5d92405e1beacf5282612747f449d245dffea7b182e2dc913a57acbe478a9f986e8b6b421add72e525c9d34def8ffbfe22967dd15
-  data.tar.gz: 743a9373b0646e76ace34001ae95937555c1aa00eea2c9bbcc4b6d6896f4784d67d1ecd07b4e7116182de60066c01d5ab4468c595f2f68f0a9ad401baf727a69
+  metadata.gz: d9e2285aa182a610b45b757707a26edad1e2ae342ce7ba62609c6a486f247fe3beaaad9e7df39a2ce2077b099b1a31edd53b1732fcdcde1d5b7253da648a7bdb
+  data.tar.gz: a9fad3831aa447433ee0969eb839d8e21245a29e955b1602ba560b75a989c8737c10c1489474d3982a7f71398407adfb9900968a240fd3cd677b05990e9dc3de

data/README.md

@@ -3,7 +3,7 @@
 [![CircleCI](https://circleci.com/gh/Intellifarm/my_john_deere_api.svg?style=svg)](https://circleci.com/gh/Intellifarm/my_john_deere_api)
 
 This client allows you to connect the [MyJohnDeere API](https://developer.deere.com/#!documentation)
-without having to code your own oauth process, API requests, and pagination.
+without having to code your own oAuth process, API requests, and pagination.
 
 * Works with Rails, but does not require it
 * Supports both sandbox and live mode
@@ -23,6 +23,7 @@ without having to code your own oauth process, API requests, and pagination.
   * [Contribution Definitions](#contribution-definitions)
   * [Organizations](#organizations)
   * [Assets](#assets)
+  * [Asset Locations](#asset-locations)
 * [Direct API Requests](#direct-api-requests)
   * [GET](#get)
   * [POST](#post)
@@ -435,6 +436,128 @@ asset.save
 ```
 
 
+### [Asset Locations](https://developer.deere.com/#!documentation&doc=.%2Fmyjohndeere%2Fassets.htm)
+
+Handles an asset's locations. Asset Location collections support the following methods:
+
+* create(attributes)
+* all
+* count
+* first
+
+An individual location supports the following methods:
+
+* timestamp
+* geometry
+* measurement\_data
+
+```ruby
+asset = organizations.assets.first
+# => the first asset returned by the organization
+
+asset.locations
+# => collection of locations belonging to this asset
+
+location = asset.locations.first
+# => the first location returned by the asset. Note that locations do not have their own id's
+#    in the JD platform, and therefore cannot be requested individually via a "find" method.
+
+location.timestamp
+# => "2019-11-11T23:00:00.000Z"
+#    John Deere includes 3 decimal places in the format, but does not actually
+#    store fractions of a second, so it will always end in ".000". This is
+#    important, because timestamps must be unique.
+
+location.geometry
+# =>  a GeoJSON formatted hash, for example:
+#     {
+#       "type"=>"Feature",
+#       "geometry"=>{
+#         "geometries"=>[
+#             {
+#               "coordinates"=>[-95.123456, 40.123456], 
+#               "type"=>"Point"
+#             }
+#           ],
+#         "type"=>"GeometryCollection"
+#       }
+#     }
+
+location.measurement_data
+# =>  the status details of this location, for example:
+#     [
+#       {
+#         "@type"=>"BasicMeasurement",
+#         "name"=>"[Soil Temperature](http://example.com/current_temperature)", 
+#         "value"=>"21.0", 
+#         "unit"=>"°C"
+#       }
+#     ]
+```
+
+The `create` method creates the location in the John Deere platform, and returns the newly created
+object from John Deere. However, there will be no new information since there is no unique ID
+generated. The timestamp submitted (which defaults to "now") will be rounded
+to the nearest second.
+
+```ruby
+locaton = asset.locatons.create(
+  # You can pass fractional seconds, but they will be truncated by JD.
+  timestamp: "2019-11-11T23:00:00.123Z",
+
+  # JD requires more complicated JSON geometry, but this client will convert a simple
+  # set of lat/long coordinates into the larger format automatically.
+  geometry: [-95.123456, 40.123456],
+
+  # This is a list of "measurements"
+  measurement_data: [
+    {
+      name: 'Temperature',
+      value: '68.0',
+      unit: 'F'
+    }
+  ]
+)
+
+location.timestamp
+# =>  "2019-11-11T23:00:00.000Z"
+#     Note that the timestamp's fractional second is truncated by John Deere, though they
+#     still return the record with three digits of precision.
+
+location.geometry
+# =>  a GeoJSON formatted hash in its larger format
+#     {
+#       "type"=>"Feature",
+#       "geometry"=>{
+#         "geometries"=>[
+#             {
+#               "coordinates"=>[-95.123456, 40.123456], 
+#               "type"=>"Point"
+#             }
+#           ],
+#         "type"=>"GeometryCollection"
+#       }
+#     }
+
+location.measurement_data
+#     [
+#       {
+#         "@type"=>"BasicMeasurement",
+#         "name"=>"Temperature", 
+#         "value"=>"68.0", 
+#         "unit"=>"F"
+#       }
+#     ]
+
+```
+
+There is no updating or deleting of a location. The newest location record always acts as the status
+for the given asset, and is what appears on the map view.
+
+Note that locations are called "Asset Locations" in John Deere, but we call the association "locations", as in
+`asset.locations`, for brevity.
+
+
 ## Direct API Requests
 
 While the goal of the client is to eliminate the need to make/interpret calls to the John Deere API, it's important
@@ -544,7 +667,7 @@ Custom errors help clearly identify problems when using the client:
 * **InvalidRecordError** is raised when bad input has been given, in an attempt to create or update
   a record on the John Deere platform.
 * **MissingContributionDefinitionIdError** is raised when the optional contribution\_definition\_id
-  has not been set in the client, but an operation has been attempted that requires it - like 
+  has not been set in the client, but an operation has been attempted that requires it - like
   creating an asset in the John Deere platform.
 * **TypeMismatchError** is raised when a model is instantiated, typically when a record is received
   from John Deere and is being converted into a Ruby object. Model instantiation is normally handled

data/lib/my_john_deere_api/version.rb

@@ -1,3 +1,3 @@
 module MyJohnDeereApi
-  VERSION='2.3.3'
+  VERSION='2.3.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: my_john_deere_api
 version: !ruby/object:Gem::Version
-  version: 2.3.3
+  version: 2.3.4
 platform: ruby
 authors:
 - Jaime Bellmyer
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-17 00:00:00.000000000 Z
+date: 2020-02-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: vcr