The AgSpy API is a simple data API which returns information pertaining to moisture and other conditions for agricultural sites (fields) employing AgSpy probes. Requests are made via web service, and the response data represents a JSON object.
The primary unit of management from the perspective of AgSpy is the Site, which corresponds to a plot of land on which crops are grown (and in which AgSpy probes are installed). Sites are identified by a unique 4-byte integer value (the Site ID). The Site ID is the only value required in order to retrieve the AgSpy API data in its simplest form, as the data is not considered sensitive and is retrieved on a per-site basis rather than en masse.
Web Service URL: https://agspy.aquaspy.com/Proxies/SiteService.asmx
Web Methods:
This method allows for the retrieval of AgSpy data with regards to a specific Site (indicated by the siteID parameter). It is used for obtaining current information about Site conditions.
The response is a string representing a JSON object which contains the current, critical AgSpy information for the requested Site. This information is provided on a TIOLI (take it or leave it) basis; any undesired information may simply be ignored.
The JSON object is structured as follows (the underlying .NET C# data type of the value stands in for the actual value below, encased in brackets):
{
// Site-level information
"SiteID": [int], // The unique identifier for the Site
"SiteDesc": "[string]", // Site name/description
"Latitude": [double],
"Longitude": [double],
"LocaleCode": "[string]", // The state (or similar foreign political territory) code for the Site
"SubLocaleName": "[string]", // The county (or similar foreign political territory) name
"SurveyInfo": "[string]", // Land parcel identifier
"SoilType": "[string]",
"InSeason": [boolean], // Indicates if a crop is currently planted
"HasEquipment": [boolean], // Indicates if an AgSpy probe is currently installed at/registered to the Site
"IsSuspended": [boolean], // Indicates if a paid subscription is not associated with the Site
"RegionName": "[string]", // The name of the Dealer managing the Site's "subscriber" (customer)
"CustomerName": "[string]", // The name of the Customer who owns the Site
"CurrentFieldSeasonID": [int?], // Unique identifier for the Site's current growing season (if any)
"TimeZoneInfoID": "[string]", // The time zone the Site is located within
"SensorInterval": [int], // The distance between probe sensors; in cm or inches
"DepthUnit": "[string]". // Linear measurement unit; cm or " (inches)
/****** BEGIN Season-level information; only provided if InSeason == true ******/
"PlantDate": "[datetime]",
"Duration": [int], // The duration of the season, in days
"ProjectedHarvestDate": "[datetime]", // PlantDate + Duration
"CropType": "[string]",
"UseAutomation": [boolean], // Indicates that automated refill estimation is in use
"RootDepthSensorIndex": [int?], // The lowest sensor (if any) on which roots have been detected
"MoistureLevel": "[string]", // Description of current soil moisture
"MoisturePercentage": [int?], // % of total possible moisture available for root consumption
"DaysToEmpty": [int?], // Days until MoisturePercentage = 0
"LastIrrigationDate": "[datetime?]",
"LastIrrigationDepthSensorIndex": [int?], // The lowest sensor on which irrigation was last detected
"InstallDepth": [int], // Depth of top active sensor (in cm or inches)
"LastReportedTimestamp": "[datetime?]", // Last receipt of data transmitted by the comm tower
"CurrentSeasonDay": [int], // Number of days since plant date
"SummaryFullPoint": [double?], // Current aggregate full point
"UseManualFullPoint": [boolean], // Indicates that the manual FP supplants the summary FP
"ManualFullPoint": [double], // Manually assigned full point
"UpperActiveSensorIndex": [int], // Index of top sensor actively included in monitoring
"LowerActiveSensorIndex": [int], // Index of bottom sensor actively included in monitoring
"ActiveRootZoneSensorIndex": [int], // Sensor index of lowest sensor included in the Active Root Zone
"MoisturePercentage": [double?], // % of total moisture available in the Active Root Zone*
"MoisturePercentageAllSensors": [double?], // % of total possible moisture available across all active sensors
"MoisturePercentagePrior": [double?], // % of total possible moisture available 24 hours prior to last data
"OptimumUpper": [double], // % specifying upper limit of optimum band
"OptimumLower": [double], // % specifying lower limit of optimum band
"MoistureValues": [double[]], // Array of the most recent individual sensor moisture values
"EcValues": [double[]], // Array of the most recent individual sensor Ec values
"TemperatureValues": [double[]], // Array of the most recent individual sensor temperature values
"LastWeatherInformationTimestamp": "[datetime?]", // The timestamp of the most recently reported CT weather sensor data (if available)
"LastAirTemperature": [double?], // The most recent air temperature reading
"AirTemperature24HourMinimum": [double?], // The low air temp. in the last 24 hours
"AirTemperature24HourMaximum": [double?], // The high air temp in the last 24 hours
"LastHumidity": [double?], // The most recent relative humidity reading (%)
"Humidity24HourMinimum": [double?], // The low relative humidity reading (%) in the last 24 hours
"Humidity24HourMaximum": [double?], // The high relative humidity reading (%) in the last 24 hours
"Precipitation24HourTotal": [double?], // Total precipitation in the last 24 hours (CT rain gauge)
"CumulativePrecipitation": [double?], // Season-to-date cumulative precipitation (CT rain gauge)
"GrowingDegreeDays24HourTotal": [double?], // Growing degree days accumulated in the last 24 hours
"GrowingDegreeDaysSeasonTotal": [double?], // Growing degree days accumulated in the season-to-date
"SeasonEvents": [ // Array of events which have occurred during the season
{
"EventType": "[string]", // Text description of the type of event
"AutomationEventType": "[string]", // If EventType == "Automation", the event sub-type (IrrigationDetection, etc.)
"EventDate": "[datetime]", // Date of the event
"EventTime": "[TimeSpan]", // Time of day of the event (adjusted to site's timezone)
"EventData": "[string]", // Text description of event details
"Comment": "[string]" // Supplemental information provided manually by users
},
…
],
"ProbeProductCode": "[string]", // Probe model number
"ProbeDSN": "[string]", // Probe serial number
"GatewayProductCode": "[string]", // Comm tower model number
"GatewayDSN": "[string]", // Comm tower serial number
"FirmwareVersion": [int?], // Comm tower firmware version #
/****** END Season-level information ******/
"ReplyTimestamp": "[datetime]" // UTC timestamp of this response
}
Notes:
((RootDepthSensorIndex - UpperActiveSensorIndex) * SensorInterval) + InstallDepth
((LastIrrigationDepthSensorIndex - UpperActiveSensorIndex) * SensorInterval) + InstallDepth
These methods allow for retrieval of historical sensor data for the current season of an AgSpy Site. Both methods require the fieldSeasonID parameter, which is obtained from the CurrentFieldSeasonID property of the JSON object returned from the GetSiteApiData call.
GetSeasonApiData is the seeding call; it returns all AgSpy sensor data collected since the beginning of the season. The expectation is that this is called once, and then the differential method is called subsequently.
The data structure of the response (common to both methods) is as follows:
{
"Success": [boolean], // Indicates if the call was successful
"HasPublicMessage": [boolean],
"Messages": [string[]], // Provides info about exception, if encountered
"Data": {
"SiteID": [int],
"FieldSeasonID": [int],
"ReferenceTimestamp": "[datetime?]",
"MaxReadTimestampUTC": "[datetime]", // The timestamp of the most recent sensor readings
"SeasonData": [ // An array of sets of readings
{
"[datetime]": { // The timestamp of a set of readings
"M": [double[]], // The moisture values of the reading, indexed from top to bottom sensor
"E": [double[]], // The Ec values of the reading
"T": [double[]], // The temperature values of the reading
"SM": [double], // The moisture summary value (%)
"SE": [double] // The Ec summary value
}
},
...
]
}
}
Unlike the sensor data returned in the GetSiteApiData call, the arrays (M, E, T) are truncated to include only sensors which are in use; for example, if the top two sensors of a 12-sensor probe are being omitted (usually because they are above ground), only ten values will appear in these arrays.
The MaxReadTimestampUTC value is necessary for calls to the GetSeasonDifferentialApiData method (passed as the referenceTimestamp parameter); it indicates that only data collected after that timestamp should be returned. The value should be stored and updated after each call for use in the subsequent differential retrieval. The format of the timestamp should be preserved; however, the value needs to be url-encoded when parameterized.