CropManage API - Documentation

Users must authenticate before performing data requests. Once authenticated an access_token is used for data requests.
Before you may authenticate with the Web API you must register with https://cropmanage.ucanr.edu. Once registered, you can use your username and password in the Web API authentication process.

Version 2.0 Released

Version 2.0 Web API is now available. Version 2.0 API methods will be prefixed with a "/v2/" in the url (for example, "v2/ranches.json"). Version 2.0 Web API methods either replace existing methods or offer additional API endpoints. We recommend using the version 2.0 whenever possible, since the older API methods will be phased out over time. Here are some of the changes we made in version 2.0:

We made version 2.0 API calls as restful as possible.
Some of the calls are now transitioning to JSON format only since XML format is becoming outdated.
Version 2.0 uses Snake Cased parameters ("PlantingName", for example, instead of "planting_name"), which should be easier for caller code to consume.
API URLs are prefixed with "/v2/"

Authentication

Authentication consists of an HTTPS POST of the username and password.

Usage:

HTTP Header Requirements:

Content-type: application/x-www-form-urlencoded

POST username and password to: https://api.cropmanage.ucanr.edu/Token
POST Parameters:

username=[email_address]
password=[your_password]
grant_type=password

Example:

POST https://api.cropmanage.ucanr.edu/Token
Content-type: application/x-www-form-urlencoded
Body: username=name@email.com&password=$Hello123&grant_type=password

Response:

This returns a JSON response with an access_token and other parameters.

{

"access_token":"[access_token]",
"token_type":"bearer",
"expires_in":1209599,
"userName":"name@email.com",
".issued":"Wed, 04 Mar 2015 17:56:03 GMT",
".expires":"Wed, 18 Mar 2015 17:56:03 GMT"

}

The access_token is then used for get Data requests.

Data Requests

GET data using a valid path specifying the data output type. An access_token is required in the http header. For each request add “Authorization: Bearer [access_token]” to be authorized for requests. The example below will list all the ranches associated with the authenticated user in JSON format.

Example:

GET https://api-cropmanage.ucanr.edu/ranches/list.json
Authorization: Bearer [access_token]

CommodityType

Returns commodity type data

API	Description
GET v2/commodity-types.json	Returns a complete list of commodity types in CropManage.

CommodityTypeRanch

Returns commodity type data associated with a specific ranch.

API	Description
POST v2/ranches/{ranchGuid}/commodity-types.{ext}	Saves a commodity type ranch association. This association determines what commodity types are available for a ranch.

CropStage

Web API to access crop stages

API	Description
GET v2/crop-stages.json?commodityTypeId={commodityTypeId}	Returns a list of crop stages associated with a commodity type

CropType

Web API to access crop types

API	Description
GET v2/crop-types.{ext}?includePrevious={includePrevious}&commodityTypeId={commodityTypeId}	Returns a list of all crop types in the system.
GET v2/crop-types/{cropTypeId}.{ext}	Get crop type data, based on ID
GET v2/ranches/{ranchGuid}/commodity-types/{commodityTypeId}/crop-types.{ext}?shouldFilterUnassociated={shouldFilterUnassociated}	Returns a list of crop types associated with a ranch. Normally, a ranch is only associated with a handful of commodity types and a select number of crop types.

CutEvent

API	Description
POST v2/cut-events.{ext}	Creates or updates a cut event
DELETE v2/cut-events/{id}.{ext}	Deletes a cut event
GET v2/cut-events/{id}.{ext}	Returns cut event data

ETWeatherEvent

API	Description
POST v2/et-weather-events.{ext}	Saves an ET weather event.
GET v2/plantings/{plantingId}/et-weather-events.json	Returns a list of ET data associated with a planting.

FertilizationEvent

API methods used for managing fertilization events

API	Description
GET v2/fertilization-events/{id}.{ext}	Returns a fertilization event
PUT v2/fertilization-events/{id}.{ext}	Updates a fertilization event
DELETE v2/fertilization-events/{id}.{ext}	Deletes a fertilization event
GET v2/fertilization-events/{id}/recommendation.{ext}?soilSampleEventDate={soilSampleEventDate}&daysToNextFertilization={daysToNextFertilization}&fertilizationsPerMonth={fertilizationsPerMonth}&eventDate={eventDate}&nInWater={nInWater}	Get CropManage recommendation for a fertilization event
POST v2/fertilization-recommendation.{ext}	Single Call API endpoint for fertilization recommendation
POST v2/plantings/{plantingId}/fertilization-events.{ext}	Creates a new fertilization event

FertilizationEventWell

API for managing fertilization event wells, used to calculate N in water

API	Description
GET v2/fertilization-events/{eventId}/wells.{ext}	Returns a list of wells associated with a fertilization event
GET v2/fertilization-event-wells/{Id}.{ext}	Returns a well associated with a fertilization event

Fertilizer

Web API for managing fertilizers

API	Description
GET v2/ranches/{ranchGuid}/fertilizers.{ext}	Returns a list of fertilizers associated with a ranch
POST v2/ranches/{ranchGuid}/fertilizers/{fertilizerId}.{ext}	Add a fertilizer to a ranch.
DELETE v2/ranches/{ranchGuid}/fertilizers/{id}.{ext}	Delete a fertilizer from a ranch
GET v2/ranches/{ranchGuid}/fertilizers/available.{ext}	Returns a list of fertilizers that are not associated with the ranch but is available for use.

IrrigationEvent

API used to manage irrigation events

API	Description
DELETE v2/irrigation-events/{id}.{ext}	Deletes an irrigation event
GET v2/irrigation-events/{id}.{ext}	Returns an irrigation event
GET v2/irrigation-events/{id}/recommendations-interval-summary.{ext}	Returns CropManage irrigation interval recommendation for a specific irrigation event
POST v2/irrigation-recommendation.{ext}	Single call Web API endpoint for irrigation recommendations. This Web API call can be used to request irrigation recommendations from CropManage, without having to first set up ranches or plantings.
POST v2/irrigation-recommendations.{ext}	Single call Web API which returns multiple recommendations
GET v2/plantings/{plantingId}/irrigation-events/details.{ext}	Returns detailed irrigation data for a planting, including reference ET, canopy cover, average canopy.
GET v2/plantings/{plantingId}/irrigation-events/recommendation-summary.{ext}?eventDate={eventDate}&irrigationMethodId={irrigationMethodId}&eventId={eventId}&customDeficit={customDeficit}	Get an irrigation recommendation depending on various inputs, including event date and irrigation method.
POST v2/season-et.{ext}	Endpoint for the public ET calculator
PUT v3/irrigation-events/{id}.{ext}	Updates an irrigation event
POST v3/plantings/{plantingId}/irrigation-events.{ext}	Creates an irrigation event

LotPlantingWell

API	Description
GET v2/plantings/{plantingId}/wells.{ext}	Returns a list of wells associated with a planting.

Maturity

API	Description
GET v2/maturities.{ext}	Returns a list of maturities, used primarily for Alfalfa

MicroSprinkler

API	Description
GET v2/microsprinklers.{ext}	Returns a list of micro sprinklers

Planting

Web API for Plantings

API	Description
GET v2/plantings/{id}.{ext}	Returns planting details.
DELETE v2/plantings/{plantingId}.{ext}	Deletes a planting
GET v2/plantings/{plantingId}/events.{ext}	Returns events from a specific planting
GET v2/plantings/{plantingId}/rainfall.{ext}	Returns rainfall data
GET v2/plantings/{plantingId}/totals/applied-water.json?startDate={startDate}&endDate={endDate}	Given planting ID, start and end dates, return total applied water
GET v2/ranches/{ranchGuid}/plantings.{ext}?active={active}&commodityTypeId={commodityTypeId}	Returns a list of plantings from a specific ranch. The list can be filtered to only return active plantings or plantings associated with a specific commodity type.
PUT v3/plantings/{plantingId}.json	Updates a planting
POST v3/ranches/{ranchGuid}/plantings.json	Creates a new planting.

Ranch

API for managing ranches

API	Description
GET v2/ranches.{ext}	Returns a list of ranches that the user has access to
DELETE v2/ranches/{ranchGuid}.json	Deletes a ranch
GET v2/ranches/{ranchGuid}.json	Returns basic ranch information.
GET v2/ranches/{ranchGuid}/permissions.{ext}	Retrieves a user's ranch planting permissions.
GET v2/ranches/{ranchGuid}/users/{userId}/permissions.json	Returns a user's ranch permissions
POST v3/ranches.{ext}	Creates a new ranch
PUT v3/ranches/{ranchGuid}.json	Updates ranch information

RanchLot

API	Description
DELETE v2/lots/{lotId}.json	Deletes a planting area from ranch
GET v2/lots/{lotId}.json	Returns planting area details
GET v2/ranches/{ranchGuid}/lots.json	Returns a list of planting areas associated with a ranch
PUT v3/lots/{id}.json	Updates a planting area
POST v3/ranches/{ranchGuid}/lots.json	Create a new planting area

RanchWell

API	Description
GET v2/ranches/{id}/ranch-wells.{ext}	Returns a list of wells associated with a ranch
POST v2/ranches/{ranchGuid}/wells.json	Adds a well to a ranch
DELETE v2/ranches/{ranchGuid}/wells/{wellId}.json	Deletes a well from a ranch
PUT v2/ranches/{ranchGuid}/wells/{wellId}.json	Updates a well
GET v2/wells/{wellId}.json	Returns well details

Region

API	Description
GET v2/regions.{ext}	Returns a list of regions in CropManage. Current regions are in California and Hawaii.

SoilMoisture

API for managing soil sensor data

API	Description
GET v2/plantings/{plantingId}/soil-moisture-data.{ext}	Returns soil moisture data for a planting. The returned data is grouped by soil sensors.

SoilSampleEvent

API for managing soil sample events

API	Description
POST v2/plantings/{plantingId}/soil-sample-events.{ext}	Creates a new soil sample event.
DELETE v2/soil-sample-events/{id}.{ext}	Delete a soil sample event
PUT v2/soil-sample-events/{id}.{ext}	Updates a soil sample event

SoilType

API	Description
GET v2/lots/{ranchLotId}/soil-types.{ext}	WARNING: This call is deprecated. CropManage no longer uses the SoilTypeJSON model. Return the soil type associated with a given lot
GET v2/soil-types.{ext}	Returns a list of all soil types in the database. This is a simple list of soil types. To retrieve soil types in more detail, call /soil-types/list.{ext}
GET v2/soil-web.{ext}?lat={lat}&lng={lng}	A simple call that retrieves soil web data, given coordinates. This call is intended to be used with single call web API which requires soil properties. Warning: This is restricted to registered 3rd party applications to prevent abuse.

TissueSampleEvent

API	Description
DELETE v2/tissue-sample-events/{id}.{ext}	Delete tissue sample event
GET v2/tissue-sample-events/{id}.{ext}	Returns tissue sample event details
POST v3/plantings/{plantingId}/tissue-sample-events.{ext}	Create tissue sample event
PUT v3/tissue-sample-events/{eventId}.{ext}	Update tissue sample event

TissueSampleLocation

API	Description
GET v2/tissue-sample-locations.{ext}	Returns a list of tissue sample locations.

TissueSampleNutrient

API	Description
GET v2/tissue-sample-nutrients.{ext}	Returns a list of tissue sample nutrients

UserDetail

API	Description
GET v2/user-detail.{ext}	Get current logged in user's information

Users

API	Description
GET v2/ranches/{ranchGuid}/users.json	Get users associated with a ranch.
POST v2/ranches/{ranchGuid}/users/{userId}.json	Add a user to a ranch
DELETE v2/ranches/{ranchGuid}/users/{userIdTarget}.json	Remove user from ranch

WeatherAPI

Controller used to fetch a list of weather service API records

API	Description
GET v2/weatherapis.{ext}	This controller is used to access Weather services records, like CIMIS and HoboLink.

WeatherStation

API used to manage weather stations

API	Description
POST v2/ranches/{ranchGuid}/weather-stations.{ext}	Add weather stations to a ranch.
GET v2/ranches/{ranchGuid}/weather-stations.{ext}	Returns weather stations associated with a ranch
DELETE v2/ranches/{ranchGuid}/weather-stations/{stationId}.{ext}	Delete weather station from ranch
GET v2/weather-stations.{ext}?activeOnly={activeOnly}&ranchGuid={ranchGuid}&suppressZeroET={suppressZeroET}	Return all weather stations in the database
GET v2/weather-stations/{id}.{ext}?ranchGuid={ranchGuid}	Get details for a specific weather station
GET v2/weather-stations/{stationId}/missingRecords.json