Agworld User API Documentation

Introduction

The Agworld API is an implementation of the JSON API specification. It is currently Read-Only.

Example Reference Client Implementation

Here is a link to an example reference client implementation written in Ruby: https://github.com/agworld/agworld_api_client

URL

In the examples below, please substitute <url> with the appropriate url for the instance that you are connecting with. A non-exhaustive list of Agworld instances is listed below:

  • Australia - https://my.agworld.com.au
  • The United States - https://us.agworld.co
  • New Zealand - https://nz.agworld.co

Content-Type

Clients must include the following headers with each request:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

The API will include the following headers with each response:

Content-Type: application/vnd.api+json

Authentication

Authentication is token based. If you wish to request additional Agworld API Access please contact Agworld support: https://help.agworld.com/en/articles/2497766-how-to-contact-agworld-customer-success

The token must be supplied along with each request in one of two ways:

  1. As a request parameter e.g.

     curl <url>/user_api/v1/fields?api_token=token \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Accept: application/vnd.api+json'
    
  2. As a header parameter e.g.

     curl <url>/user_api/v1/fields \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Accept: application/vnd.api+json' \
     -H 'Api-Token: token'
    

Features

The following JSON API functionality is implemented for each resource’s endpoints (index and show). Please check the JSON API specification for more detail on each of these options.

Note The URL’s passed to curl below are not URL-encoded. This makes reading them easier but it means that they will need to be properly encoded before using them yourself. For example [ and ] become %5B and %5D respectively.

  • filter (index only)

    Allows the filtering of the records returned in the response by the specified attribute. The list of filterable attributes is defined for each resource in its specific section.

      curl <url>/user_api/v1/farms?filter[name]=Home \
      -H 'Content-Type: application/vnd.api+json' \
      -H 'Accept: application/vnd.api+json' \
      -H 'Api-Token: token'
    
  • sorting (index only)

    Allows the sorting of the records in the response by the specified attribute. The list of sortable attributes is defined for each resource in its specific section.

      curl <url>/user_api/v1/farms?sort=name \
      -H 'Content-Type: application/vnd.api+json' \
      -H 'Accept: application/vnd.api+json' \
      -H 'Api-Token: token'
    
  • pagination (index only)

    The Agworld API uses pagination for each index endpoint with a default page size of 10 and a maximum of 100. To fetch a specific page, a client should provide a page[number] parameter. It is also possible to optionally override the size of the page returned by providing a page[size] parameter.

      curl '<url>/user_api/v1/farms?page[number]=2&page[size]=5' \
      -H 'Content-Type: application/vnd.api+json' \
      -H 'Accept: application/vnd.api+json' \
      -H 'Api-Token: token'
    
  • include

    For efficiency, it is possible to side-load related records in the same request. The list of includable records is defined for each resource in its specific section.

      curl <url>/user_api/v1/farms?include=company \
      -H 'Content-Type: application/vnd.api+json' \
      -H 'Accept: application/vnd.api+json' \
      -H 'Api-Token: token'
    
  • fields

    For efficiency, it is possible to only return a subset of the fields available on a resource. The list of visible attributes is defined for each resource in its specific section.

      curl '<url>/user_api/v1/farms?fields[farms]=name' \
      -H 'Content-Type: application/vnd.api+json' \
      -H 'Accept: application/vnd.api+json' \
      -H 'Api-Token: token'
    

Webhooks

You can subscribe to HTTP Webhooks for Create, Update and Delete for each of the sources above. After adding a Webhook any records that you have access to read will trigger these events and a POST request will be made against the webhook URL with the record’s payload in the same JSON API format that the rest of the API uses.

The payload also contains a ‘meta’ attribute called ‘event’ which will be one of “Create”, “Update”, “Delete” and signifies the event that took place.

Object lifecycle and Webhook event ‘bundling’

In order to better represent user behaviour and to prevent redundant events we have 2 mechanisms that limit Webhook events from firing.

  1. Initial creation window. There is a 4 second window immediately after an object is created where any updates are counted as part of the original creation. This means that if a user (or automated process) creates and immediately updates an object there will only be one Webhook invocation for the create event but it will include any changes from the update. A Webhook invocation for an update event will not happen in this case.

  2. Subsequent updates window. Update Webhooks will fire a minimum of 1 minute apart. Any edits within a minute will extend this window and be ‘batched’ into one update event. This extending can indefinitely delay the update until ongoing updates stop happening within the 1 minute window.

Activities

Get an activity

Endpoint

GET user_api/v1/activities/:id

Parameters

  • required api_token
    A valid api token to authenticate the user
  • required id
    Unique ID of the activity.

Request

Route

GET user_api/v1/activities/987625?api_token=secret

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret

Response

Simulated Response

Response Fields

  • id
    Unique ID of the activity.
  • activity_category
    Situation / category of the activity. e.g. weed management, harvest etc.
  • activity_type
    Type of activity. e.g. workorder, recommendation etc.
  • application_method
    Application method for the activity. e.g. boomspray.
  • approved
    Returns true if the activity has been approved and false if the activity is a draft.
  • area
    Total area of fields specified for the activity inputs.
  • author_company_id
    ID of the company that authored the activity.
  • author_company_name
    Company name that the author user belongs to.
  • author_user_id
    ID of the user who authored the activity.
  • author_user_name
    Activity author name.
  • band
    Banding percentage for activity application.
  • chemical_cost
    Total chemical cost of the activity inputs.
  • colour_id
    Colour id of the activity
  • colour_name
    Colour name of the activity in english
  • comments
    Author comments for the activity.
  • company_id
    ID of the company that the activity is for.
  • company_name
    Company name for whom the activity is for.
  • completed
    Actuals have been created for all fields for this activity. Always true for actuals.
  • completed_at
    Timestamp when the activity was completed.
  • cost_per_area
    Cost per area of the activity.
  • droplet_size
    Droplet size to be used for application.
  • due_at
    Date that the activity is due.
  • expiration_date
    Timestamp when the authors advice on the activity expires.
  • fertilizer_cost
    Total fertilizer cost of the activity inputs.
  • humidity
    Observed humidity when the activity was created.
  • nozzle_type
    Type of nozzle to be used for application. e.g. cone.
  • operation_cost
    Total operational cost of the activity inputs.
  • operator_company_id
    ID of the operator company assigned to complete the activity.
  • operator_company_name
    Assigned operator company name.
  • operation_cost
    Total operational cost of the activity inputs.
  • parent_id
    Unique id of the activity that this activity was converted from.
  • reason_name
    Reason for the activity.
  • reason_text
    Reason for the activity.
  • season_phase
    Season phase that the activity should be completed.
  • seed_cost
    Total seed cost of the activity inputs.
  • skip_row
    Skip row percentage for activity application.
  • specialisation
    Purpose for this activity. Usually 'general', but may be something like 'harvest'.
  • started_at
    Timestamp when an activity was started.
  • tags
    Tags for this activity.
  • temperature
    Observed temperature when the activity was created.
  • timing
    Author specified timing for when the activity should be completed. e.g planting.
  • title
    Title of the activity.
  • total_cost
    Total cost of the activity inputs.
  • total_volume
    Total volume (calculated as water_rate multiplied by area).
  • updated_at
    Timestamp of the last activity update.
  • water_rate
    Total (liquid) application rate of the activity.
  • weather_conditions
    Observed weather conditions when the activity was created.
  • wind_direction
    Observed wind direction when the activity was created.
  • wind_speed
    Observed wind speed when the activity was created.
  • activity_inputs
    Inputs in activity, e.g. product, fertilizer, seed.
  • activity_inputs. activity_input_order
    Mix order for inputs of an activity.
  • activity_inputs. cost_per_area
    Cost per area.
  • activity_inputs. grazing_interval
    Interval (days) between application and time when safe to graze stock.
  • activity_inputs. harvest_interval
    Interval (days) before the crop can be harvested.
  • activity_inputs. input_name
    Name of the activity input. e.g. Roundup PowerMAX Herbicide.
  • activity_inputs. input_type
    Type of activity input. e.g. product, seed, operation.
  • activity_inputs. cost_activity_id
    If input_type is "Cost Activity", then this is the id of the Cost Activity. Otherwise it's null.
  • activity_inputs. crop_variety_id
    If input_type is "Seed", then this is the id of the Crop Variety. Otherwise it's null.
  • activity_inputs. product_id
    If input_type is "Product", then this is the id of the Product. Otherwise it's null.
  • activity_inputs. mix_method
    Mix method for activity input.
  • activity_inputs. plantback_interval
    Interval (days) between application and planting next crop.
  • activity_inputs. product_categories
    Product category of activity input. e.g. herbicide, fungicide.
  • activity_inputs. product_substance
    Substance of activity input. e.g. liquid, solid, gas.
  • activity_inputs. rain_fast_interval
    Interval (hours) between application time and precipitation.
  • activity_inputs. rate
    Rate of application for the activity input.
  • activity_inputs. re_entry_interval
    Interval (hours) between application and time when safe to re-enter treated area.
  • activity_inputs. stockfeed_inverval
    Interval (days) between application and time when safe to cut for stockfeed. e.g. hay.
  • activity_inputs. total_area
    Total applied area of activity input.
  • activity_inputs. total_cost
    Total cost of activity input.
  • activity_inputs. total_count
    Total count of activity input (expressed as each). e.g. count of seeds.
  • activity_inputs. total_time
    Total time for operational activity inputs. e.g. labor
  • activity_inputs. total_volume
    Total volume of activity input.
  • activity_inputs. total_weight
    Total weight of activity input.
  • activity_inputs. unit_cost
    Unit cost of activity input.
  • activity_inputs. tags
    Tags for this activity input
  • activity_fields
    Fields in activity.
  • activity_fields. area
    Total applied area of field
  • activity_fields. area_ratio
    Proportion of the total activity area that this field's area makes up.
  • activity_fields. chemical_cost
    Chemical cost for the activity field.
  • activity_fields. crop_stage
    Crop stage description.
  • activity_fields. farm_id
    Unique ID of the farm this field belongs to.
  • activity_fields. farm_name
    Name of the farm this field belongs to.
  • activity_fields. fertilizer_cost
    Fertilizer cost for the activity field.
  • activity_fields. field_id
    Unique ID of the field.
  • activity_fields. field_name
    Name of the field.
  • activity_fields. operation_cost
    Operational cost for the activity field.
  • activity_fields. seed_cost
    Seed cost for the activity field.
  • activity_fields. season_id
    Unique ID of the season that the activity is applied to the field
  • activity_fields. season_phase
    Season phase that the activity field should be completed.
  • activity_fields. total_cost
    Total cost for the activity field.
  • activity_fields. crop
    Crops used in activity fields.
  • activity_fields.crops. crop_blend
    Reason for crop blend.
  • activity_fields.crops. crop_grade
    Classification of seed. e.g. Prime?
  • activity_fields.crops. crop_name
    Crop name.
  • activity_fields.crops. crop_use
    End purpose of crop. e.g. hay, seed quality, use.
  • activity_fields.crops. variety_name
    Variety name.
  • activity_problems
    Problems in activity.
  • activity_problems. description
    Description of activity problem.
  • activity_problems. infestation
    Infestation rate of pest or problem.
  • activity_problems. pest_name
    Name of pest or problem.
  • activity_problems. severity
    Severity of activity problem. e.g high.
  • activity_problems. stage
    Stage of activity problem. e.g. eggs, 4 leaf.
  • activity_harvest
    Harvest details for activities with specialisation set to 'harvest'.
  • activity_harvest. harvested_weight
    Weight of what was harvested in this activity.
  • activity_harvest. price
    Price of what was harvested in this activity.
  • activity_harvest. grade
    Grade of what was harvested in this activity, e.g. 'Fodder'.
  • activity_harvest. destination
    Destination for what was harvested in this activity, e.g. 'Silo 1'
  • job_activities
    Other activities that are members of this same job.
  • job_activities. activity_id
    Unique ID of the activity.
  • job_activities. activity_type
    Type of activity. e.g. workorder, recommendation etc.
  • job_activities. author_user_name
    Activity author name.
  • job_activities. author_user_id
    ID of the user who authored the activity.
  • job_activities. author_company_name
    Company name that the author user belongs to.
  • job_activities. author_company_id
    ID of the company that authored the activity.
  • operator_users
    Details of the assigned operator users.
  • operator_users. id
    the user's id.
  • operator_users. name
    The user's name.
  • operator_users. licenses
    List of licenses that apply to this user or company.
  • operator_users.licenses. name
    The name or type of the license.
  • operator_users.licenses. description
    The license description.
  • operator_users.licenses. authority
    The issuing authority for the licenese.
  • operator_users.licenses. number
    The license number.
  • operator_users.licenses. valid_from
    The date from which this license is valid.
  • operator_users.licenses. valid_to
    The date after which this license is no longer valid.
  • operator_company_licenses
    List of licenses that apply to this user or company.
  • operator_company_licenses. name
    The name or type of the license.
  • operator_company_licenses. description
    The license description.
  • operator_company_licenses. authority
    The issuing authority for the licenese.
  • operator_company_licenses. number
    The license number.
  • operator_company_licenses. valid_from
    The date from which this license is valid.
  • operator_company_licenses. valid_to
    The date after which this license is no longer valid.
  • farm_assets
    Assets in activity.
  • farm_assets. id
    Unique ID of the asset
  • farm_assets. name
    The asset's name
  • farm_assets. description
    The asset's description
  • farm_assets. category
    The asset's category

Relationships

  • company
    The company that the activity belongs to.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "id": "987625",
    "type": "activities",
    "links": {
      "self": "http://example.org/user_api/v1/activities/987625"
    },
    "attributes": {
      "activity_category": null,
      "application_method": null,
      "approved": false,
      "area": "28 acre",
      "author_company_id": 987913,
      "author_company_name": "Grow Co",
      "author_user_id": 987123,
      "author_user_name": "Grow Joe",
      "band": null,
      "chemical_cost": "135.974 dollar",
      "comments": null,
      "company_id": 987913,
      "company_name": "Grow Co",
      "completed": true,
      "completed_at": "2011-06-15T10:30:00.000+08:00",
      "cost_per_area": "4.85623 dollar/acre",
      "created_at": "2011-06-15T10:30:00.000+08:00",
      "created_on": "web",
      "droplet_size": null,
      "due_at": null,
      "expiration_date": null,
      "farm_assets": [
        {
          "id": 987634,
          "name": "Truck",
          "description": "Vehicle.",
          "category": "Vehicle"
        }
      ],
      "fertilizer_cost": "0 dollar",
      "humidity": null,
      "nozzle_type": null,
      "operator_company_id": 987913,
      "operator_company_name": "Grow Co",
      "operator_company_licenses": [
        {
          "name": "TEST COMPANY LICENSE",
          "description": "description",
          "authority": "",
          "number": "12345",
          "valid_from": "2011-03-15",
          "valid_to": "2012-03-15"
        }
      ],
      "operation_cost": "0 dollar",
      "operator_users": [
        {
          "id": 987123,
          "name": "Grow Joe",
          "licenses": [
            {
              "name": "TEST USER LICENSE",
              "description": "description",
              "authority": "",
              "number": "34567",
              "valid_from": "2011-03-15",
              "valid_to": "2012-03-15"
            }
          ]
        }
      ],
      "parent_id": -1,
      "reason_name": null,
      "reason_text": null,
      "season_phase": null,
      "seed_cost": "0 dollar",
      "skip_row": null,
      "specialisation": "general",
      "started_at": null,
      "tags": [
        "Test 0",
        "Test 1"
      ],
      "temperature": null,
      "timing": null,
      "title": "Summer Knockdown 1",
      "total_cost": "135.974 dollar",
      "total_volume": "209.537 gal",
      "activity_type": "ActualActivity",
      "updated_at": "2014-06-15T10:30:00.000+08:00",
      "water_rate": "7.48346 gal/acre",
      "weather_conditions": null,
      "wind_direction": null,
      "wind_speed": null,
      "activity_inputs": [
        {
          "activity_input_order": 0,
          "cost_per_area": "4.85623 dollar/acre",
          "grazing_interval": null,
          "harvest_interval": null,
          "input_name": "Product Turf",
          "input_type": "Product",
          "cost_activity_id": null,
          "crop_variety_id": null,
          "product_id": 987622,
          "mix_method": "per_area",
          "plantback_interval": null,
          "product_categories": [],
          "product_substance": "liquid",
          "rain_fast_interval": null,
          "rate": "1 mL/ha",
          "re_entry_interval": null,
          "stockfeed_inverval": null,
          "tags": [],
          "total_area": "0 acre",
          "total_cost": "135.974 dollar",
          "total_count": "0 each",
          "total_time": "0 h",
          "total_volume": "0.00299339 gal",
          "total_weight": "0 lbs",
          "unit_cost": "12 dollar/mL"
        }
      ],
      "activity_fields": [
        {
          "area": "28 acre",
          "area_ratio": 1.0,
          "chemical_cost": "135.974 dollar",
          "crops": [],
          "crop_stage": null,
          "farm_id": 987623,
          "farm_name": "Sunny Downs",
          "fertilizer_cost": "0 dollar",
          "field_id": 987101,
          "field_name": "Field 1",
          "operation_cost": "0 dollar",
          "seed_cost": "0 dollar",
          "season_id": 987911,
          "season_phase": null,
          "total_cost": "135.974 dollar"
        }
      ],
      "activity_problems": [
        {
          "description": "Danger",
          "infestation": null,
          "pest_name": "Insects",
          "severity": null,
          "stage": "2 leaf"
        }
      ],
      "activity_harvest": {},
      "job_activities": [
        {
          "activity_id": 987627,
          "activity_type": "WorkOrder",
          "author_user_name": "Grow Joe",
          "author_user_id": 987123,
          "author_company_name": "Grow Co",
          "author_company_id": 987913
        }
      ],
      "job_id": 978111,
      "job_status": "complete",
      "colour_id": 1,
      "colour_name": "Red"
    },
    "relationships": {
      "company": {
        "links": {
          "self": "http://example.org/user_api/v1/activities/987625/relationships/company",
          "related": "http://example.org/user_api/v1/activities/987625/company"
        }
      }
    }
  }
}

Listing activities

Endpoint

GET user_api/v1/activities

Parameters

  • required api_token
    A valid api token to authenticate the user
  • filter. name
    FILTER - Title of the activity.
  • filter. company_id
    FILTER - ID of the company that the activity is for.
  • filter. activity_type
    FILTER - Type of activity. e.g. workorder, recommendation etc.
  • filter. approved
    FILTER - Returns true if the activity has been approved and false if the activity is a draft.
  • filter. author_user_id
    FILTER - ID of the user who authored the activity.
  • filter. author_company_id
    FILTER - ID of the company that authored the activity.
  • filter. operator_user_id
    FILTER - ID of the operator assigned to complete the activity.
  • filter. operator_company_id
    FILTER - ID of the operator company assigned to complete the activity.
  • filter. parent_id
    FILTER - Unique id of the activity that this activity was converted from.
  • filter. updated_at
    FILTER - Return activities updated since the provided timestamp. e.g. "2011-09-12T10:30:20+08:00".
  • filter. colour_id
    FILTER - Colour id of the activity, can be colour_id(s) or no_colour with empty string

Request

Route

GET user_api/v1/activities?api_token=secret&filter[name]=Summer+Knockdown+1

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret
filter={"name"=>"Summer Knockdown 1"}

Response

Simulated Response

Response Fields

  • id
    Unique ID of the activity.
  • activity_category
    Situation / category of the activity. e.g. weed management, harvest etc.
  • activity_type
    Type of activity. e.g. workorder, recommendation etc.
  • application_method
    Application method for the activity. e.g. boomspray.
  • approved
    Returns true if the activity has been approved and false if the activity is a draft.
  • area
    Total area of fields specified for the activity inputs.
  • author_company_id
    ID of the company that authored the activity.
  • author_company_name
    Company name that the author user belongs to.
  • author_user_id
    ID of the user who authored the activity.
  • author_user_name
    Activity author name.
  • band
    Banding percentage for activity application.
  • chemical_cost
    Total chemical cost of the activity inputs.
  • colour_id
    Colour id of the activity
  • colour_name
    Colour name of the activity in english
  • comments
    Author comments for the activity.
  • company_id
    ID of the company that the activity is for.
  • company_name
    Company name for whom the activity is for.
  • completed
    Actuals have been created for all fields for this activity. Always true for actuals.
  • completed_at
    Timestamp when the activity was completed.
  • cost_per_area
    Cost per area of the activity.
  • droplet_size
    Droplet size to be used for application.
  • due_at
    Date that the activity is due.
  • expiration_date
    Timestamp when the authors advice on the activity expires.
  • fertilizer_cost
    Total fertilizer cost of the activity inputs.
  • humidity
    Observed humidity when the activity was created.
  • nozzle_type
    Type of nozzle to be used for application. e.g. cone.
  • operation_cost
    Total operational cost of the activity inputs.
  • operator_company_id
    ID of the operator company assigned to complete the activity.
  • operator_company_name
    Assigned operator company name.
  • operation_cost
    Total operational cost of the activity inputs.
  • parent_id
    Unique id of the activity that this activity was converted from.
  • reason_name
    Reason for the activity.
  • reason_text
    Reason for the activity.
  • season_phase
    Season phase that the activity should be completed.
  • seed_cost
    Total seed cost of the activity inputs.
  • skip_row
    Skip row percentage for activity application.
  • specialisation
    Purpose for this activity. Usually 'general', but may be something like 'harvest'.
  • started_at
    Timestamp when an activity was started.
  • tags
    Tags for this activity.
  • temperature
    Observed temperature when the activity was created.
  • timing
    Author specified timing for when the activity should be completed. e.g planting.
  • title
    Title of the activity.
  • total_cost
    Total cost of the activity inputs.
  • total_volume
    Total volume (calculated as water_rate multiplied by area).
  • updated_at
    Timestamp of the last activity update.
  • water_rate
    Total (liquid) application rate of the activity.
  • weather_conditions
    Observed weather conditions when the activity was created.
  • wind_direction
    Observed wind direction when the activity was created.
  • wind_speed
    Observed wind speed when the activity was created.
  • activity_inputs
    Inputs in activity, e.g. product, fertilizer, seed.
  • activity_inputs. activity_input_order
    Mix order for inputs of an activity.
  • activity_inputs. cost_per_area
    Cost per area.
  • activity_inputs. grazing_interval
    Interval (days) between application and time when safe to graze stock.
  • activity_inputs. harvest_interval
    Interval (days) before the crop can be harvested.
  • activity_inputs. input_name
    Name of the activity input. e.g. Roundup PowerMAX Herbicide.
  • activity_inputs. input_type
    Type of activity input. e.g. product, seed, operation.
  • activity_inputs. cost_activity_id
    If input_type is "Cost Activity", then this is the id of the Cost Activity. Otherwise it's null.
  • activity_inputs. crop_variety_id
    If input_type is "Seed", then this is the id of the Crop Variety. Otherwise it's null.
  • activity_inputs. product_id
    If input_type is "Product", then this is the id of the Product. Otherwise it's null.
  • activity_inputs. mix_method
    Mix method for activity input.
  • activity_inputs. plantback_interval
    Interval (days) between application and planting next crop.
  • activity_inputs. product_categories
    Product category of activity input. e.g. herbicide, fungicide.
  • activity_inputs. product_substance
    Substance of activity input. e.g. liquid, solid, gas.
  • activity_inputs. rain_fast_interval
    Interval (hours) between application time and precipitation.
  • activity_inputs. rate
    Rate of application for the activity input.
  • activity_inputs. re_entry_interval
    Interval (hours) between application and time when safe to re-enter treated area.
  • activity_inputs. stockfeed_inverval
    Interval (days) between application and time when safe to cut for stockfeed. e.g. hay.
  • activity_inputs. total_area
    Total applied area of activity input.
  • activity_inputs. total_cost
    Total cost of activity input.
  • activity_inputs. total_count
    Total count of activity input (expressed as each). e.g. count of seeds.
  • activity_inputs. total_time
    Total time for operational activity inputs. e.g. labor
  • activity_inputs. total_volume
    Total volume of activity input.
  • activity_inputs. total_weight
    Total weight of activity input.
  • activity_inputs. unit_cost
    Unit cost of activity input.
  • activity_inputs. tags
    Tags for this activity input
  • activity_fields
    Fields in activity.
  • activity_fields. area
    Total applied area of field
  • activity_fields. area_ratio
    Proportion of the total activity area that this field's area makes up.
  • activity_fields. chemical_cost
    Chemical cost for the activity field.
  • activity_fields. crop_stage
    Crop stage description.
  • activity_fields. farm_id
    Unique ID of the farm this field belongs to.
  • activity_fields. farm_name
    Name of the farm this field belongs to.
  • activity_fields. fertilizer_cost
    Fertilizer cost for the activity field.
  • activity_fields. field_id
    Unique ID of the field.
  • activity_fields. field_name
    Name of the field.
  • activity_fields. operation_cost
    Operational cost for the activity field.
  • activity_fields. seed_cost
    Seed cost for the activity field.
  • activity_fields. season_id
    Unique ID of the season that the activity is applied to the field
  • activity_fields. season_phase
    Season phase that the activity field should be completed.
  • activity_fields. total_cost
    Total cost for the activity field.
  • activity_fields. crop
    Crops used in activity fields.
  • activity_fields.crops. crop_blend
    Reason for crop blend.
  • activity_fields.crops. crop_grade
    Classification of seed. e.g. Prime?
  • activity_fields.crops. crop_name
    Crop name.
  • activity_fields.crops. crop_use
    End purpose of crop. e.g. hay, seed quality, use.
  • activity_fields.crops. variety_name
    Variety name.
  • activity_problems
    Problems in activity.
  • activity_problems. description
    Description of activity problem.
  • activity_problems. infestation
    Infestation rate of pest or problem.
  • activity_problems. pest_name
    Name of pest or problem.
  • activity_problems. severity
    Severity of activity problem. e.g high.
  • activity_problems. stage
    Stage of activity problem. e.g. eggs, 4 leaf.
  • activity_harvest
    Harvest details for activities with specialisation set to 'harvest'.
  • activity_harvest. harvested_weight
    Weight of what was harvested in this activity.
  • activity_harvest. price
    Price of what was harvested in this activity.
  • activity_harvest. grade
    Grade of what was harvested in this activity, e.g. 'Fodder'.
  • activity_harvest. destination
    Destination for what was harvested in this activity, e.g. 'Silo 1'
  • job_activities
    Other activities that are members of this same job.
  • job_activities. activity_id
    Unique ID of the activity.
  • job_activities. activity_type
    Type of activity. e.g. workorder, recommendation etc.
  • job_activities. author_user_name
    Activity author name.
  • job_activities. author_user_id
    ID of the user who authored the activity.
  • job_activities. author_company_name
    Company name that the author user belongs to.
  • job_activities. author_company_id
    ID of the company that authored the activity.
  • operator_users
    Details of the assigned operator users.
  • operator_users. id
    the user's id.
  • operator_users. name
    The user's name.
  • operator_users. licenses
    List of licenses that apply to this user or company.
  • operator_users.licenses. name
    The name or type of the license.
  • operator_users.licenses. description
    The license description.
  • operator_users.licenses. authority
    The issuing authority for the licenese.
  • operator_users.licenses. number
    The license number.
  • operator_users.licenses. valid_from
    The date from which this license is valid.
  • operator_users.licenses. valid_to
    The date after which this license is no longer valid.
  • operator_company_licenses
    List of licenses that apply to this user or company.
  • operator_company_licenses. name
    The name or type of the license.
  • operator_company_licenses. description
    The license description.
  • operator_company_licenses. authority
    The issuing authority for the licenese.
  • operator_company_licenses. number
    The license number.
  • operator_company_licenses. valid_from
    The date from which this license is valid.
  • operator_company_licenses. valid_to
    The date after which this license is no longer valid.
  • farm_assets
    Assets in activity.
  • farm_assets. id
    Unique ID of the asset
  • farm_assets. name
    The asset's name
  • farm_assets. description
    The asset's description
  • farm_assets. category
    The asset's category

Relationships

  • company
    The company that the activity belongs to.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": [
    {
      "id": "987625",
      "type": "activities",
      "links": {
        "self": "http://example.org/user_api/v1/activities/987625"
      },
      "attributes": {
        "activity_category": null,
        "application_method": null,
        "approved": false,
        "area": "28 acre",
        "author_company_id": 987913,
        "author_company_name": "Grow Co",
        "author_user_id": 987123,
        "author_user_name": "Grow Joe",
        "band": null,
        "chemical_cost": "135.974 dollar",
        "comments": null,
        "company_id": 987913,
        "company_name": "Grow Co",
        "completed": true,
        "completed_at": "2011-06-15T10:30:00.000+08:00",
        "cost_per_area": "4.85623 dollar/acre",
        "created_at": "2011-06-15T10:30:00.000+08:00",
        "created_on": "web",
        "droplet_size": null,
        "due_at": null,
        "expiration_date": null,
        "farm_assets": [
          {
            "id": 987634,
            "name": "Truck",
            "description": "Vehicle.",
            "category": "Vehicle"
          }
        ],
        "fertilizer_cost": "0 dollar",
        "humidity": null,
        "nozzle_type": null,
        "operator_company_id": 987913,
        "operator_company_name": "Grow Co",
        "operator_company_licenses": [
          {
            "name": "TEST COMPANY LICENSE",
            "description": "description",
            "authority": "",
            "number": "12345",
            "valid_from": "2011-03-15",
            "valid_to": "2012-03-15"
          }
        ],
        "operation_cost": "0 dollar",
        "operator_users": [
          {
            "id": 987123,
            "name": "Grow Joe",
            "licenses": [
              {
                "name": "TEST USER LICENSE",
                "description": "description",
                "authority": "",
                "number": "34567",
                "valid_from": "2011-03-15",
                "valid_to": "2012-03-15"
              }
            ]
          }
        ],
        "parent_id": -1,
        "reason_name": null,
        "reason_text": null,
        "season_phase": null,
        "seed_cost": "0 dollar",
        "skip_row": null,
        "specialisation": "general",
        "started_at": null,
        "tags": [
          "Test 0",
          "Test 1"
        ],
        "temperature": null,
        "timing": null,
        "title": "Summer Knockdown 1",
        "total_cost": "135.974 dollar",
        "total_volume": "209.537 gal",
        "activity_type": "ActualActivity",
        "updated_at": "2014-06-15T10:30:00.000+08:00",
        "water_rate": "7.48346 gal/acre",
        "weather_conditions": null,
        "wind_direction": null,
        "wind_speed": null,
        "activity_inputs": [
          {
            "activity_input_order": 0,
            "cost_per_area": "4.85623 dollar/acre",
            "grazing_interval": null,
            "harvest_interval": null,
            "input_name": "Product Turf",
            "input_type": "Product",
            "cost_activity_id": null,
            "crop_variety_id": null,
            "product_id": 987622,
            "mix_method": "per_area",
            "plantback_interval": null,
            "product_categories": [],
            "product_substance": "liquid",
            "rain_fast_interval": null,
            "rate": "1 mL/ha",
            "re_entry_interval": null,
            "stockfeed_inverval": null,
            "tags": [],
            "total_area": "0 acre",
            "total_cost": "135.974 dollar",
            "total_count": "0 each",
            "total_time": "0 h",
            "total_volume": "0.00299339 gal",
            "total_weight": "0 lbs",
            "unit_cost": "12 dollar/mL"
          }
        ],
        "activity_fields": [
          {
            "area": "28 acre",
            "area_ratio": 1.0,
            "chemical_cost": "135.974 dollar",
            "crops": [],
            "crop_stage": null,
            "farm_id": 987623,
            "farm_name": "Sunny Downs",
            "fertilizer_cost": "0 dollar",
            "field_id": 987101,
            "field_name": "Field 1",
            "operation_cost": "0 dollar",
            "seed_cost": "0 dollar",
            "season_id": 987911,
            "season_phase": null,
            "total_cost": "135.974 dollar"
          }
        ],
        "activity_problems": [
          {
            "description": "Danger",
            "infestation": null,
            "pest_name": "Insects",
            "severity": null,
            "stage": "2 leaf"
          }
        ],
        "activity_harvest": {},
        "job_activities": [
          {
            "activity_id": 987627,
            "activity_type": "WorkOrder",
            "author_user_name": "Grow Joe",
            "author_user_id": 987123,
            "author_company_name": "Grow Co",
            "author_company_id": 987913
          }
        ],
        "job_id": 978111,
        "job_status": "complete",
        "colour_id": 1,
        "colour_name": "Red"
      },
      "relationships": {
        "company": {
          "links": {
            "self": "http://example.org/user_api/v1/activities/987625/relationships/company",
            "related": "http://example.org/user_api/v1/activities/987625/company"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://example.org/user_api/v1/activities?filter%5Bname%5D=Summer+Knockdown+1\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=10",
    "last": "http://example.org/user_api/v1/activities?filter%5Bname%5D=Summer+Knockdown+1\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=10"
  }
}

Collection Jobs

Get a collection job

Endpoint

GET user_api/v1/collection_jobs/:id

Parameters

  • required api_token
    A valid api token to authenticate the user
  • required id
    Unique ID of the collection job.
  • include. company
    INCLUDE - Sideload the company record.
  • include. field
    INCLUDE - Sideload the field record.
  • include. season
    INCLUDE - Sideload the season record.

Request

Route

GET user_api/v1/collection_jobs/829482?api_token=secret

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret

Response

Simulated Response

Response Fields

  • id
    Unique ID of the collection job.
  • assigned_company_id
    ID of the company assigned to the collection job.
  • assigned_company_name
    Name of the company assigned to the collection job.
  • assigned_user_id
    ID of the user assigned to the collection job.
  • assigned_user_name
    Name of the user assigned to the collection job.
  • author_company_id
    ID of the company that authored the collection job.
  • author_company_name
    Name of the company that authored the collection job.
  • author_user_id
    ID of the user that authored the collection job.
  • author_user_name
    Name of the user that authored the collection job.
  • auto_run_surfacing
    Boolean to indicate whether to automatically generate surfaces based on lab results returned.
  • comments
    Authored comments for the collection job.
  • company_address
    Address of the farm company that the collection job belongs to.
  • company_email
    Email of the farm company that the collection job belongs to.
  • company_id
    ID of the farm company that the collection job belongs to.
  • company_name
    Name of the farm company that the collection job belongs to.
  • company_phone_number
    Phone number of the farm company that the collection job belongs to.
  • created_at
    Timestamp of collection job creation.
  • updated_at
    Timestamp of when this collection job was last changed.
  • estimated_sample_count
    Estimate number of samples to be collected based off the field size and grid size.
  • farm_id
    ID of the farm that this collection job's field belongs to.
  • farm_name
    Name of the farm that this collection job's field belongs to.
  • field_area
    Area of the field for this collection job's season.
  • field_boundary
    Boundary of the field for this collection job's season as a GeoJSON MultiPolygon.
  • field_id
    ID of the field that this collection job belongs to.
  • field_name
    Name of the field that this collection job belongs to.
  • manual_upload
    This indicates if the results for this job are to be manually uploaded or not.
  • planned_collection_date
    Date the the sample collecting is planned to occur on.
  • sample_at
    Timestamp of when the samples were collected.
  • season_id
    ID of the season that this collection job belongs to.
  • season_name
    Name of the season that this collection job belongs to.
  • status
    Status the job can be in. One of: Not ready, Ready to collect, Submitted to lab, Lab import failed, Lab analysis complete, Processing for precision, Ready for precision, Completed.
  • state_updated_at
    Timestamp of when this collection job's state was last changed.
  • strategy
    Strategy taken to collect the samples. One of: grid, point.
  • lab_details
    Details about the lab that will analyse this collection job's samples.
  • lab_details. account_number
    Account number to be used by the lab for this collection job.
  • lab_details. address
    Address of the lab to send the samples to.
  • lab_details. email
    Email of the lab to send the samples to.
  • lab_details. id
    ID of the lab to send the samples to.
  • lab_details. name
    Name of the lab to send the samples to.
  • lab_details. phone_number
    Phone number of the lab to send the samples to.
  • lab_details. purchase_order_number
    Purchase order number to be used by the lab for this collection job.
  • requested_points
    If strategy = point, this shows the requested points to sample, as a array of GeoJSON Points.
  • sampling_grid
    If strategy = grid, details of the sampling grid to be used.
  • sampling_grid. id
    ID of the sampling grid to be used.
  • sampling_grid. angle
    Angle of the grid to be used, where a straight grid has an angle of 0.
  • sampling_grid. grid_size
    Area of the square bounded by 4 grid points.
  • sampling_grid. origin
    Intersection of one of the grid points (any of them), as a GeoJSON Point.
  • previous_sampled_date
    Timestamp of when samples were last collected for this field.
  • previous_samples
    Points of samples that were last collected for this field, as an array of GeoJSON Points.
  • planned_depths
    Ranges of the different planned sampling depths to be collected for this job.
  • planned_depths. min_depth
    Starting depth of this planned depth.
  • planned_depths. max_depth
    Ending depth of this planned depth.
  • planned_depths. surface_this_depth
    Boolean to indicate if this depth will be processed for surfacing. Only true for 1 depth per collection job.
  • planned_depths. lab_tests
    Tests (suite/package or individual) required for the lab to run for all samples at this planned depth.
  • planned_depths.lab_tests. code
    Lab test code/ID for the suite/package or individual test to be run.
  • planned_depths.lab_tests. description
    Description of the lab test.
  • planned_depths.lab_tests. display_name
    Display name for the lab test that the Agworld user sees.
  • planned_depths.lab_tests. sample_type
    Type of sample collected, e.g. soil.
  • planned_depths. samples
    Details of samples that were collected for this collection job.
  • planned_depths.samples. samples_id
    ID of this sample. This is globally unique, unlike the barcode.
  • planned_depths.samples. samples_actual_min_depth
    Actual starting depth of this sample. Usually the same as the planned min_depth.
  • planned_depths.samples. samples_actual_max_depth
    Actual ending depth of this sample. Usually the same as the planned max_depth.
  • planned_depths.samples. samples_barcode
    Barcode (or manually generated ID) for this sample. Used by labs to identify this sample.
  • planned_depths.samples. samples_analysed_at
    Timestamp of when this sample was analysed by the lab.
  • planned_depths.samples. samples_created_at
    Timestamp of sample creation. Effectively when the sample was collected.
  • planned_depths.samples. samples_updated_at
    Timestamp of when this sample was last changed.
  • planned_depths.samples. samples_lab_code
    ID/code provided by the lab for this sample. Usually a report id.
  • planned_depths.samples. samples_location
    Location of this collected sample point, as a GeoJSON Point.
  • planned_depths.samples. samples_sample_type
    Type of sample collected, e.g. soil.
  • planned_depths.samples. samples_results
    Hash of lab results for this sample, with keys of Modus Test IDs (c.f: https://bitbucket.org/modus/analysis-nomenclature/src), and values of the result (a string with a number and units)
  • job_state_history
    Audit record of when this collection job's state changed and by whom.
  • job_state_history. created_at
    Timestamp of when this collection job's state changed.
  • job_state_history. old_state
    State of the job prior to the change.
  • job_state_history. new_state
    State of the job subsequent to the change.
  • job_state_history. user_id
    ID of the user who triggered the change of job's state.
  • job_state_history. user_name
    Name of the user who triggered the change of job's state. "Automatic" if triggered by the system.

Relationships

  • company
    Farm company that the collection job belongs to.
  • field
    Field that the collection job belongs to.
  • season
    Season that the collection job belongs to.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "id": "829482",
    "type": "collection_jobs",
    "links": {
      "self": "http://example.org/user_api/v1/collection_jobs/829482"
    },
    "attributes": {
      "assigned_company_id": 987914,
      "assigned_company_name": "Sample Collector Company",
      "assigned_user_id": null,
      "assigned_user_name": null,
      "author_company_id": 987913,
      "author_company_name": "Grow Co",
      "author_user_id": 987123,
      "author_user_name": "Grow Joe",
      "auto_run_surfacing": true,
      "comments": null,
      "company_address": "123 co street, Belmont, California, 72354, United States",
      "company_email": "grow.co@farmingproductions.com",
      "company_id": 987913,
      "company_name": "Grow Co",
      "company_phone_number": "+15417543010",
      "created_at": "2011-06-15T10:30:00.000+08:00",
      "estimated_sample_count": 3,
      "farm_id": 987623,
      "farm_name": "Sunny Downs",
      "field_area": "11.3312 ha",
      "field_boundary": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                171.9124,
                -43.89123
              ],
              [
                171.9144,
                -43.89493
              ],
              [
                171.9134,
                -43.89135
              ],
              [
                171.9124,
                -43.89123
              ]
            ]
          ]
        ]
      },
      "field_id": 987101,
      "field_name": "Field 1",
      "planned_collection_date": null,
      "sampled_at": "2011-06-17T10:30:00.000+08:00",
      "season_id": 987911,
      "season_name": "2010",
      "status": "Lab analysis complete",
      "state_updated_at": "2011-06-20T10:30:00.000+08:00",
      "strategy": "grid",
      "updated_at": "2011-06-15T10:30:00.000+08:00",
      "lab_details": {
        "account_number": "AN8524",
        "purchase_order_number": "PO8524",
        "address": "123 lab st, Berkeley, California, 91734, United States",
        "email": null,
        "id": 245924,
        "name": "Soil Lab Display Name",
        "phone_number": "+15417543010"
      },
      "requested_points": null,
      "sampling_grid": {
        "id": 72644,
        "angle": 104.238246,
        "grid_size": "5.26091 ha",
        "origin": {
          "type": "Point",
          "coordinates": [
            171.91249,
            -43.89123
          ]
        }
      },
      "previous_sampled_date": "2011-06-10T10:30:00.000+08:00",
      "previous_samples": [
        {
          "type": "Point",
          "coordinates": [
            171.91245,
            -43.89129
          ]
        }
      ],
      "planned_depths": [
        {
          "min_depth": "0 cm",
          "max_depth": "20 cm",
          "surface_this_depth": true,
          "lab_test": [
            {
              "code": "TEST-SUITE-1",
              "description": "Test Suite Description",
              "display_name": "Test Suite 1 Display",
              "sample_type": "soil"
            }
          ],
          "samples": [
            {
              "id": 623612,
              "actual_min_depth": "0 cm",
              "actual_max_depth": "20 cm",
              "barcode": "XH23A32K392A983",
              "analysed_at": "2011-06-18T10:30:00.000+08:00",
              "created_at": "2011-06-15T10:30:00.000+08:00",
              "updated_at": "2011-06-15T10:30:00.000+08:00",
              "lab_code": null,
              "location": {
                "type": "Point",
                "coordinates": [
                  171.91245,
                  -43.89129
                ]
              },
              "sample_type": "soil",
              "results": {
                "S-CACO3.15": "3 %",
                "S-P-B2-1:10.01.03": "2 lbs/acre"
              }
            }
          ]
        }
      ],
      "job_state_history": [
        {
          "created_at": "2011-06-15T10:30:00.000+08:00",
          "old_status": "Not ready",
          "new_status": "Ready to collect",
          "user_id": null,
          "user_name": "Automatic"
        },
        {
          "created_at": "2011-06-15T10:30:00.000+08:00",
          "old_status": "Ready to collect",
          "new_status": "Submitted to lab",
          "user_id": null,
          "user_name": "Automatic"
        },
        {
          "created_at": "2011-06-15T10:30:00.000+08:00",
          "old_status": "Submitted to lab",
          "new_status": "Lab analysis complete",
          "user_id": null,
          "user_name": "Automatic"
        }
      ],
      "manual_upload": false
    },
    "relationships": {
      "company": {
        "links": {
          "self": "http://example.org/user_api/v1/collection_jobs/829482/relationships/company",
          "related": "http://example.org/user_api/v1/collection_jobs/829482/company"
        }
      },
      "field": {
        "links": {
          "self": "http://example.org/user_api/v1/collection_jobs/829482/relationships/field",
          "related": "http://example.org/user_api/v1/collection_jobs/829482/field"
        }
      },
      "season": {
        "links": {
          "self": "http://example.org/user_api/v1/collection_jobs/829482/relationships/season",
          "related": "http://example.org/user_api/v1/collection_jobs/829482/season"
        }
      }
    }
  }
}

Listing collection jobs

Endpoint

GET user_api/v1/collection_jobs

Parameters

  • required api_token
    A valid api token to authenticate the user
  • filter. assigned_company_id
    FILTER - ID of the company assigned to the collection job.
  • filter. assigned_user_id
    FILTER - ID of the user assigned to the collection job.
  • filter. company_id
    FILTER - ID of the farm company that the collection job belongs to.
  • filter. comments
    FILTER - Authored comments for the collection job.
  • filter. author_user_id
    FILTER - ID of the user that authored the collection job.
  • filter. author_company_id
    FILTER - ID of the company that authored the collection job.
  • filter. job_status
    FILTER - Status the job can be in. One of: Not ready, Ready to collect, Submitted to lab, Lab import failed, Lab analysis complete, Processing for precision, Ready for precision, Completed.
  • filter. updated_since
    FILTER - Timestamp of when this collection job was last changed.
  • filter. season_id
    FILTER - ID of the season that this collection job belongs to.
  • include. company
    INCLUDE - Sideload the company record.
  • include. field
    INCLUDE - Sideload the field record.
  • include. season
    INCLUDE - Sideload the season record.

Request

Route

GET user_api/v1/collection_jobs?api_token=secret

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret

Response

Simulated Response

Response Fields

  • id
    Unique ID of the collection job.
  • assigned_company_id
    ID of the company assigned to the collection job.
  • assigned_company_name
    Name of the company assigned to the collection job.
  • assigned_user_id
    ID of the user assigned to the collection job.
  • assigned_user_name
    Name of the user assigned to the collection job.
  • author_company_id
    ID of the company that authored the collection job.
  • author_company_name
    Name of the company that authored the collection job.
  • author_user_id
    ID of the user that authored the collection job.
  • author_user_name
    Name of the user that authored the collection job.
  • auto_run_surfacing
    Boolean to indicate whether to automatically generate surfaces based on lab results returned.
  • comments
    Authored comments for the collection job.
  • company_address
    Address of the farm company that the collection job belongs to.
  • company_email
    Email of the farm company that the collection job belongs to.
  • company_id
    ID of the farm company that the collection job belongs to.
  • company_name
    Name of the farm company that the collection job belongs to.
  • company_phone_number
    Phone number of the farm company that the collection job belongs to.
  • created_at
    Timestamp of collection job creation.
  • updated_at
    Timestamp of when this collection job was last changed.
  • estimated_sample_count
    Estimate number of samples to be collected based off the field size and grid size.
  • farm_id
    ID of the farm that this collection job's field belongs to.
  • farm_name
    Name of the farm that this collection job's field belongs to.
  • field_area
    Area of the field for this collection job's season.
  • field_boundary
    Boundary of the field for this collection job's season as a GeoJSON MultiPolygon.
  • field_id
    ID of the field that this collection job belongs to.
  • field_name
    Name of the field that this collection job belongs to.
  • manual_upload
    This indicates if the results for this job are to be manually uploaded or not.
  • planned_collection_date
    Date the the sample collecting is planned to occur on.
  • sample_at
    Timestamp of when the samples were collected.
  • season_id
    ID of the season that this collection job belongs to.
  • season_name
    Name of the season that this collection job belongs to.
  • status
    Status the job can be in. One of: Not ready, Ready to collect, Submitted to lab, Lab import failed, Lab analysis complete, Processing for precision, Ready for precision, Completed.
  • state_updated_at
    Timestamp of when this collection job's state was last changed.
  • strategy
    Strategy taken to collect the samples. One of: grid, point.
  • lab_details
    Details about the lab that will analyse this collection job's samples.
  • lab_details. account_number
    Account number to be used by the lab for this collection job.
  • lab_details. address
    Address of the lab to send the samples to.
  • lab_details. email
    Email of the lab to send the samples to.
  • lab_details. id
    ID of the lab to send the samples to.
  • lab_details. name
    Name of the lab to send the samples to.
  • lab_details. phone_number
    Phone number of the lab to send the samples to.
  • lab_details. purchase_order_number
    Purchase order number to be used by the lab for this collection job.
  • requested_points
    If strategy = point, this shows the requested points to sample, as a array of GeoJSON Points.
  • sampling_grid
    If strategy = grid, details of the sampling grid to be used.
  • sampling_grid. id
    ID of the sampling grid to be used.
  • sampling_grid. angle
    Angle of the grid to be used, where a straight grid has an angle of 0.
  • sampling_grid. grid_size
    Area of the square bounded by 4 grid points.
  • sampling_grid. origin
    Intersection of one of the grid points (any of them), as a GeoJSON Point.
  • previous_sampled_date
    Timestamp of when samples were last collected for this field.
  • previous_samples
    Points of samples that were last collected for this field, as an array of GeoJSON Points.
  • planned_depths
    Ranges of the different planned sampling depths to be collected for this job.
  • planned_depths. min_depth
    Starting depth of this planned depth.
  • planned_depths. max_depth
    Ending depth of this planned depth.
  • planned_depths. surface_this_depth
    Boolean to indicate if this depth will be processed for surfacing. Only true for 1 depth per collection job.
  • planned_depths. lab_tests
    Tests (suite/package or individual) required for the lab to run for all samples at this planned depth.
  • planned_depths.lab_tests. code
    Lab test code/ID for the suite/package or individual test to be run.
  • planned_depths.lab_tests. description
    Description of the lab test.
  • planned_depths.lab_tests. display_name
    Display name for the lab test that the Agworld user sees.
  • planned_depths.lab_tests. sample_type
    Type of sample collected, e.g. soil.
  • planned_depths. samples
    Details of samples that were collected for this collection job.
  • planned_depths.samples. samples_id
    ID of this sample. This is globally unique, unlike the barcode.
  • planned_depths.samples. samples_actual_min_depth
    Actual starting depth of this sample. Usually the same as the planned min_depth.
  • planned_depths.samples. samples_actual_max_depth
    Actual ending depth of this sample. Usually the same as the planned max_depth.
  • planned_depths.samples. samples_barcode
    Barcode (or manually generated ID) for this sample. Used by labs to identify this sample.
  • planned_depths.samples. samples_analysed_at
    Timestamp of when this sample was analysed by the lab.
  • planned_depths.samples. samples_created_at
    Timestamp of sample creation. Effectively when the sample was collected.
  • planned_depths.samples. samples_updated_at
    Timestamp of when this sample was last changed.
  • planned_depths.samples. samples_lab_code
    ID/code provided by the lab for this sample. Usually a report id.
  • planned_depths.samples. samples_location
    Location of this collected sample point, as a GeoJSON Point.
  • planned_depths.samples. samples_sample_type
    Type of sample collected, e.g. soil.
  • planned_depths.samples. samples_results
    Hash of lab results for this sample, with keys of Modus Test IDs (c.f: https://bitbucket.org/modus/analysis-nomenclature/src), and values of the result (a string with a number and units)
  • job_state_history
    Audit record of when this collection job's state changed and by whom.
  • job_state_history. created_at
    Timestamp of when this collection job's state changed.
  • job_state_history. old_state
    State of the job prior to the change.
  • job_state_history. new_state
    State of the job subsequent to the change.
  • job_state_history. user_id
    ID of the user who triggered the change of job's state.
  • job_state_history. user_name
    Name of the user who triggered the change of job's state. "Automatic" if triggered by the system.

Relationships

  • company
    Farm company that the collection job belongs to.
  • field
    Field that the collection job belongs to.
  • season
    Season that the collection job belongs to.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": [
    {
      "id": "829432",
      "type": "collection_jobs",
      "links": {
        "self": "http://example.org/user_api/v1/collection_jobs/829432"
      },
      "attributes": {
        "assigned_company_id": 987914,
        "assigned_company_name": "Sample Collector Company",
        "assigned_user_id": null,
        "assigned_user_name": null,
        "author_company_id": 987913,
        "author_company_name": "Grow Co",
        "author_user_id": 987123,
        "author_user_name": "Grow Joe",
        "auto_run_surfacing": false,
        "comments": null,
        "company_address": "123 co street, Belmont, California, 72354, United States",
        "company_email": "grow.co@farmingproductions.com",
        "company_id": 987913,
        "company_name": "Grow Co",
        "company_phone_number": "+15417543010",
        "created_at": "2011-06-15T10:30:00.000+08:00",
        "estimated_sample_count": 3,
        "farm_id": 987623,
        "farm_name": "Sunny Downs",
        "field_area": "11.3312 ha",
        "field_boundary": {
          "type": "MultiPolygon",
          "coordinates": [
            [
              [
                [
                  171.9124,
                  -43.89123
                ],
                [
                  171.9144,
                  -43.89493
                ],
                [
                  171.9134,
                  -43.89135
                ],
                [
                  171.9124,
                  -43.89123
                ]
              ]
            ]
          ]
        },
        "field_id": 987101,
        "field_name": "Field 1",
        "planned_collection_date": null,
        "sampled_at": "2011-06-10T10:30:00.000+08:00",
        "season_id": 987911,
        "season_name": "2010",
        "status": "Ready to collect",
        "state_updated_at": null,
        "strategy": "grid",
        "updated_at": "2011-06-15T10:30:00.000+08:00",
        "lab_details": {
          "account_number": "AN8524",
          "purchase_order_number": "PO8524",
          "address": "123 lab st, Berkeley, California, 91734, United States",
          "email": null,
          "id": 245924,
          "name": "Soil Lab Display Name",
          "phone_number": "+15417543010"
        },
        "requested_points": null,
        "sampling_grid": {
          "id": 72644,
          "angle": 104.238246,
          "grid_size": "5.26091 ha",
          "origin": {
            "type": "Point",
            "coordinates": [
              171.91249,
              -43.89123
            ]
          }
        },
        "previous_sampled_date": "2011-06-17T10:30:00.000+08:00",
        "previous_samples": [
          {
            "type": "Point",
            "coordinates": [
              171.91245,
              -43.89129
            ]
          }
        ],
        "planned_depths": [
          {
            "min_depth": "0 cm",
            "max_depth": "20 cm",
            "surface_this_depth": true,
            "lab_test": [],
            "samples": [
              {
                "id": 623512,
                "actual_min_depth": "0 cm",
                "actual_max_depth": "20 cm",
                "barcode": "XH23A32K395A983",
                "analysed_at": "2011-06-12T10:30:00.000+08:00",
                "created_at": "2011-06-15T10:30:00.000+08:00",
                "updated_at": "2011-06-15T10:30:00.000+08:00",
                "lab_code": null,
                "location": {
                  "type": "Point",
                  "coordinates": [
                    171.91245,
                    -43.89129
                  ]
                },
                "sample_type": "soil",
                "results": {
                  "S-CACO3.15": "3 %",
                  "S-P-B2-1:10.01.03": "2 lbs/acre"
                }
              }
            ]
          }
        ],
        "job_state_history": [
          {
            "created_at": "2011-06-15T10:30:00.000+08:00",
            "old_status": "Not ready",
            "new_status": "Ready to collect",
            "user_id": null,
            "user_name": "Automatic"
          }
        ],
        "manual_upload": false
      },
      "relationships": {
        "company": {
          "links": {
            "self": "http://example.org/user_api/v1/collection_jobs/829432/relationships/company",
            "related": "http://example.org/user_api/v1/collection_jobs/829432/company"
          }
        },
        "field": {
          "links": {
            "self": "http://example.org/user_api/v1/collection_jobs/829432/relationships/field",
            "related": "http://example.org/user_api/v1/collection_jobs/829432/field"
          }
        },
        "season": {
          "links": {
            "self": "http://example.org/user_api/v1/collection_jobs/829432/relationships/season",
            "related": "http://example.org/user_api/v1/collection_jobs/829432/season"
          }
        }
      }
    },
    {
      "id": "829482",
      "type": "collection_jobs",
      "links": {
        "self": "http://example.org/user_api/v1/collection_jobs/829482"
      },
      "attributes": {
        "assigned_company_id": 987914,
        "assigned_company_name": "Sample Collector Company",
        "assigned_user_id": null,
        "assigned_user_name": null,
        "author_company_id": 987913,
        "author_company_name": "Grow Co",
        "author_user_id": 987123,
        "author_user_name": "Grow Joe",
        "auto_run_surfacing": true,
        "comments": null,
        "company_address": "123 co street, Belmont, California, 72354, United States",
        "company_email": "grow.co@farmingproductions.com",
        "company_id": 987913,
        "company_name": "Grow Co",
        "company_phone_number": "+15417543010",
        "created_at": "2011-06-15T10:30:00.000+08:00",
        "estimated_sample_count": 3,
        "farm_id": 987623,
        "farm_name": "Sunny Downs",
        "field_area": "11.3312 ha",
        "field_boundary": {
          "type": "MultiPolygon",
          "coordinates": [
            [
              [
                [
                  171.9124,
                  -43.89123
                ],
                [
                  171.9144,
                  -43.89493
                ],
                [
                  171.9134,
                  -43.89135
                ],
                [
                  171.9124,
                  -43.89123
                ]
              ]
            ]
          ]
        },
        "field_id": 987101,
        "field_name": "Field 1",
        "planned_collection_date": null,
        "sampled_at": "2011-06-17T10:30:00.000+08:00",
        "season_id": 987911,
        "season_name": "2010",
        "status": "Lab analysis complete",
        "state_updated_at": "2011-06-20T10:30:00.000+08:00",
        "strategy": "grid",
        "updated_at": "2011-06-15T10:30:00.000+08:00",
        "lab_details": {
          "account_number": "AN8524",
          "purchase_order_number": "PO8524",
          "address": "123 lab st, Berkeley, California, 91734, United States",
          "email": null,
          "id": 245924,
          "name": "Soil Lab Display Name",
          "phone_number": "+15417543010"
        },
        "requested_points": null,
        "sampling_grid": {
          "id": 72644,
          "angle": 104.238246,
          "grid_size": "5.26091 ha",
          "origin": {
            "type": "Point",
            "coordinates": [
              171.91249,
              -43.89123
            ]
          }
        },
        "previous_sampled_date": "2011-06-10T10:30:00.000+08:00",
        "previous_samples": [
          {
            "type": "Point",
            "coordinates": [
              171.91245,
              -43.89129
            ]
          }
        ],
        "planned_depths": [
          {
            "min_depth": "0 cm",
            "max_depth": "20 cm",
            "surface_this_depth": true,
            "lab_test": [
              {
                "code": "TEST-SUITE-1",
                "description": "Test Suite Description",
                "display_name": "Test Suite 1 Display",
                "sample_type": "soil"
              }
            ],
            "samples": [
              {
                "id": 623612,
                "actual_min_depth": "0 cm",
                "actual_max_depth": "20 cm",
                "barcode": "XH23A32K392A983",
                "analysed_at": "2011-06-18T10:30:00.000+08:00",
                "created_at": "2011-06-15T10:30:00.000+08:00",
                "updated_at": "2011-06-15T10:30:00.000+08:00",
                "lab_code": null,
                "location": {
                  "type": "Point",
                  "coordinates": [
                    171.91245,
                    -43.89129
                  ]
                },
                "sample_type": "soil",
                "results": {
                  "S-CACO3.15": "3 %",
                  "S-P-B2-1:10.01.03": "2 lbs/acre"
                }
              }
            ]
          }
        ],
        "job_state_history": [
          {
            "created_at": "2011-06-15T10:30:00.000+08:00",
            "old_status": "Not ready",
            "new_status": "Ready to collect",
            "user_id": null,
            "user_name": "Automatic"
          },
          {
            "created_at": "2011-06-15T10:30:00.000+08:00",
            "old_status": "Ready to collect",
            "new_status": "Submitted to lab",
            "user_id": null,
            "user_name": "Automatic"
          },
          {
            "created_at": "2011-06-15T10:30:00.000+08:00",
            "old_status": "Submitted to lab",
            "new_status": "Lab analysis complete",
            "user_id": null,
            "user_name": "Automatic"
          }
        ],
        "manual_upload": false
      },
      "relationships": {
        "company": {
          "links": {
            "self": "http://example.org/user_api/v1/collection_jobs/829482/relationships/company",
            "related": "http://example.org/user_api/v1/collection_jobs/829482/company"
          }
        },
        "field": {
          "links": {
            "self": "http://example.org/user_api/v1/collection_jobs/829482/relationships/field",
            "related": "http://example.org/user_api/v1/collection_jobs/829482/field"
          }
        },
        "season": {
          "links": {
            "self": "http://example.org/user_api/v1/collection_jobs/829482/relationships/season",
            "related": "http://example.org/user_api/v1/collection_jobs/829482/season"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://example.org/user_api/v1/collection_jobs?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10",
    "last": "http://example.org/user_api/v1/collection_jobs?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10"
  }
}

Company

Get a company

Endpoint

GET /user_api/v1/companies/:id

Parameters

  • required api_token
    A valid api token to authenticate the user
  • required id
    Unique id of the company.

Request

Route

GET /user_api/v1/companies/987124?api_token=secret

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret

Response

Simulated Response

Response Fields

  • id
    Unique id of the company.
  • business_identifier
    Government provided business identifier. e.g. EIN in USA, ABN in Australia.
  • business_structure
    Structure of the company. e.g. Company, Partnership, Individual etc.
  • company_type
    The kind of company that this is. e.g. Farmer, Retailer, Consultant etc.
  • created_at
    Timestamp of company creation.
  • contact_email
    Default email address for the company.
  • contact_name
    Default contact person for the company.
  • description
    Text description of the company.
  • name
    Name of the company.
  • physical_location
    Physical address of the company.
  • postal_location
    Postal address of the company.
  • state_name
    Name of the state/province for this company.
  • account_number
    Placeholder for an external system ID
  • updated_at
    Timestamp of the last company update.

Relationships

  • activities
    Activities belonging to this farm company.
  • farms
    Farms belonging to this farm company.
  • seasons
    Seasons belonging to this farm company.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "id": "987124",
    "type": "companies",
    "links": {
      "self": "http://example.org/user_api/v1/companies/987124"
    },
    "attributes": {
      "business_identifier": "124",
      "business_structure": null,
      "company_type": "Farmer",
      "contact_email": "farmer.jim@farmingproductions.com",
      "contact_name": "Farmer Jim",
      "created_at": "2011-06-15T10:30:00.000+08:00",
      "description": null,
      "name": "Farming Productions",
      "physical_location": {
        "number": null,
        "street": null,
        "suburb": null,
        "city": null,
        "county": null,
        "state": null,
        "postcode": null,
        "country": "Australia",
        "latitude": -29.0779350143255,
        "longitude": 133.664062768221
      },
      "postal_location": {
        "number": null,
        "street": null,
        "suburb": null,
        "city": null,
        "county": null,
        "state": null,
        "postcode": null,
        "country": null,
        "latitude": null,
        "longitude": null
      },
      "state_name": null,
      "account_number": "12345678",
      "updated_at": "2011-06-15T10:30:00.000+08:00"
    },
    "relationships": {
      "activities": {
        "links": {
          "self": "http://example.org/user_api/v1/companies/987124/relationships/activities",
          "related": "http://example.org/user_api/v1/companies/987124/activities"
        }
      },
      "farms": {
        "links": {
          "self": "http://example.org/user_api/v1/companies/987124/relationships/farms",
          "related": "http://example.org/user_api/v1/companies/987124/farms"
        }
      },
      "seasons": {
        "links": {
          "self": "http://example.org/user_api/v1/companies/987124/relationships/seasons",
          "related": "http://example.org/user_api/v1/companies/987124/seasons"
        }
      }
    }
  }
}

Listing companies

Endpoint

GET /user_api/v1/companies

Parameters

  • required api_token
    A valid api token to authenticate the user
  • filter. name
    FILTER - Name of the company.
  • filter. company_type
    FILTER - The kind of company that this is. e.g. Farmer, Retailer, Consultant etc.
  • filter. business_identifier
    FILTER - Government provided business identifier. e.g. EIN in USA, ABN in Australia.
  • filter. updated_at
    FILTER - Return companies updated since the provided timestamp. e.g. "2011-09-12T10:30:20+08:00".

Request

Route

GET /user_api/v1/companies?api_token=secret&filter[name]=Farming+Productions&filter[company_type]=Farmer&filter[business_identifier]=124

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret
filter={"name"=>"Farming Productions", "company_type"=>"Farmer", "business_identifier"=>"124"}

Response

Simulated Response

Response Fields

  • id
    Unique id of the company.
  • business_identifier
    Government provided business identifier. e.g. EIN in USA, ABN in Australia.
  • business_structure
    Structure of the company. e.g. Company, Partnership, Individual etc.
  • company_type
    The kind of company that this is. e.g. Farmer, Retailer, Consultant etc.
  • created_at
    Timestamp of company creation.
  • contact_email
    Default email address for the company.
  • contact_name
    Default contact person for the company.
  • description
    Text description of the company.
  • name
    Name of the company.
  • physical_location
    Physical address of the company.
  • postal_location
    Postal address of the company.
  • state_name
    Name of the state/province for this company.
  • account_number
    Placeholder for an external system ID
  • updated_at
    Timestamp of the last company update.

Relationships

  • activities
    Activities belonging to this farm company.
  • farms
    Farms belonging to this farm company.
  • seasons
    Seasons belonging to this farm company.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": [
    {
      "id": "987124",
      "type": "companies",
      "links": {
        "self": "http://example.org/user_api/v1/companies/987124"
      },
      "attributes": {
        "business_identifier": "124",
        "business_structure": null,
        "company_type": "Farmer",
        "contact_email": "farmer.jim@farmingproductions.com",
        "contact_name": "Farmer Jim",
        "created_at": "2011-06-15T10:30:00.000+08:00",
        "description": null,
        "name": "Farming Productions",
        "physical_location": {
          "number": null,
          "street": null,
          "suburb": null,
          "city": null,
          "county": null,
          "state": null,
          "postcode": null,
          "country": "Australia",
          "latitude": -29.0779350143255,
          "longitude": 133.664062768221
        },
        "postal_location": {
          "number": null,
          "street": null,
          "suburb": null,
          "city": null,
          "county": null,
          "state": null,
          "postcode": null,
          "country": null,
          "latitude": null,
          "longitude": null
        },
        "state_name": null,
        "account_number": "12345678",
        "updated_at": "2011-06-15T10:30:00.000+08:00"
      },
      "relationships": {
        "activities": {
          "links": {
            "self": "http://example.org/user_api/v1/companies/987124/relationships/activities",
            "related": "http://example.org/user_api/v1/companies/987124/activities"
          }
        },
        "farms": {
          "links": {
            "self": "http://example.org/user_api/v1/companies/987124/relationships/farms",
            "related": "http://example.org/user_api/v1/companies/987124/farms"
          }
        },
        "seasons": {
          "links": {
            "self": "http://example.org/user_api/v1/companies/987124/relationships/seasons",
            "related": "http://example.org/user_api/v1/companies/987124/seasons"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://example.org/user_api/v1/companies?filter%5Bbusiness_identifier%5D=124\u0026filter%5Bcompany_type%5D=Farmer\u0026filter%5Bname%5D=Farming+Productions\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=10",
    "last": "http://example.org/user_api/v1/companies?filter%5Bbusiness_identifier%5D=124\u0026filter%5Bcompany_type%5D=Farmer\u0026filter%5Bname%5D=Farming+Productions\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=10"
  }
}

Farms

Get a farm

Endpoint

GET /user_api/v1/farms/:id

Parameters

  • required api_token
    A valid api token to authenticate the user
  • required id
    Unique id of the farm.

Request

Route

GET /user_api/v1/farms/987613?api_token=secret

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret

Response

Simulated Response

Response Fields

  • id
    Unique id of the farm.
  • company_id
    Id of the company this farm belongs to.
  • created_at
    Timestamp of farm creation.
  • description
    Text description of the farm.
  • location
    Location of the farm.
  • name
    Name of the farm.
  • reporting_region
    Optional user-populated string used for reporting.
  • updated_at
    Timestamp of the last farm update.

Relationships

  • company
    The company that the farms belongs to.
  • fields
    Fields belonging to this farm.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "id": "987613",
    "type": "farms",
    "links": {
      "self": "http://example.org/user_api/v1/farms/987613"
    },
    "attributes": {
      "company_id": 987612,
      "created_at": "2011-06-15T10:30:00.000+08:00",
      "description": "Home Farm",
      "location": {
        "number": null,
        "street": null,
        "suburb": null,
        "city": null,
        "county": null,
        "state": "Western Australia",
        "postcode": null,
        "country": "Australia",
        "latitude": -29.0779350143255,
        "longitude": 133.665562768221
      },
      "name": "Farm 1",
      "reporting_region": "Farm 1",
      "updated_at": "2011-06-15T10:30:00.000+08:00"
    },
    "relationships": {
      "company": {
        "links": {
          "self": "http://example.org/user_api/v1/farms/987613/relationships/company",
          "related": "http://example.org/user_api/v1/farms/987613/company"
        }
      },
      "fields": {
        "links": {
          "self": "http://example.org/user_api/v1/farms/987613/relationships/fields",
          "related": "http://example.org/user_api/v1/farms/987613/fields"
        }
      }
    }
  }
}

Listing farms

Endpoint

GET /user_api/v1/farms

Parameters

  • required api_token
    A valid api token to authenticate the user
  • filter. company_id
    FILTER - Id of the company this farm belongs to.
  • filter. name
    FILTER - Name of the farm.
  • filter. reporting_region
    FILTER - Optional user-populated string used for reporting.
  • filter. updated_at
    FILTER - Return farms updated since the provided timestamp. e.g. "2011-09-12T10:30:20+08:00".

Request

Route

GET /user_api/v1/farms?api_token=secret&filter[name]=Farm+1

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret
filter={"name"=>"Farm 1"}

Response

Simulated Response

Response Fields

  • id
    Unique id of the farm.
  • company_id
    Id of the company this farm belongs to.
  • created_at
    Timestamp of farm creation.
  • description
    Text description of the farm.
  • location
    Location of the farm.
  • name
    Name of the farm.
  • reporting_region
    Optional user-populated string used for reporting.
  • updated_at
    Timestamp of the last farm update.

Relationships

  • company
    The company that the farms belongs to.
  • fields
    Fields belonging to this farm.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": [
    {
      "id": "987613",
      "type": "farms",
      "links": {
        "self": "http://example.org/user_api/v1/farms/987613"
      },
      "attributes": {
        "company_id": 987612,
        "created_at": "2011-06-15T10:30:00.000+08:00",
        "description": "Home Farm",
        "location": {
          "number": null,
          "street": null,
          "suburb": null,
          "city": null,
          "county": null,
          "state": "Western Australia",
          "postcode": null,
          "country": "Australia",
          "latitude": -29.0779350143255,
          "longitude": 133.665562768221
        },
        "name": "Farm 1",
        "reporting_region": "Farm 1",
        "updated_at": "2011-06-15T10:30:00.000+08:00"
      },
      "relationships": {
        "company": {
          "links": {
            "self": "http://example.org/user_api/v1/farms/987613/relationships/company",
            "related": "http://example.org/user_api/v1/farms/987613/company"
          }
        },
        "fields": {
          "links": {
            "self": "http://example.org/user_api/v1/farms/987613/relationships/fields",
            "related": "http://example.org/user_api/v1/farms/987613/fields"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://example.org/user_api/v1/farms?filter%5Bname%5D=Farm+1\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=10",
    "last": "http://example.org/user_api/v1/farms?filter%5Bname%5D=Farm+1\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=10"
  }
}

Fields

Get a field

Endpoint

GET user_api/v1/fields/:id

Parameters

  • required api_token
    A valid api token to authenticate the user
  • required id
    Unique Id of the field.
  • season_id
    Unique Id of the season provided for extra seasonal field information.
  • include. farm
    INCLUDE - Sideload the farm record.

Request

Route

GET user_api/v1/fields/987654?api_token=secret

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret

Response

Simulated Response

Response Fields

  • id
    Unique Id of the field.
  • application_cost
    Total application costs to date for the field in the provided season.
  • area
    Area of the field for the provided season.
  • boundary
    Boundary of the field for the provided season.
  • chemical_cost
    Total chemical costs to date for the field in the provided season.
  • contractor_cost
    Total contractor costs to date for the field in the provided season.
  • created_at
    Timestamp of field creation.
  • crop_blend
    Reason for crop blend.
  • crop_grade
    Grade of the crop in the field for the provided season.
  • crop_name
    Name of the crop in the field for the provided season.
  • crop_use
    Use of the crop in the field for the provided season.
  • cropping_method
    Cropping method used in the field. e.g. dryland, irrigated.
  • description
    Description of the field.
  • fertiliser_cost
    Total fertilizer costs to date for the field in the provided season.
  • gross_margin
    Gross margin of the field for the provided season.
  • harvest_date
    Timestamp that the field has been harvested in the provided season.
  • harvested_area
    Area of the field that has been harvested in the provided season.
  • harvested_weight
    Total harvested weight for the field in the provided season.
  • irrigation
    User specified string describing irrigation method used in the field.
  • name
    Name of the field.
  • other_cost
    Total other costs to date for the field in the provided season.
  • other_income
    Total other income to date for the field in the provided season.
  • plant_spacing
    Plant spacing used in the field.
  • row_spacing
    Row spacing used in the field.
  • season_id
    Unique Id of the season provided for extra seasonal field information.
  • seed_cost
    Total seed cost to date for the field in the provided season.
  • planting_date
    Timestamp that the field has been planted in the provided season.
  • updated_at
    Timestamp of the last field update.
  • variety_name
    Name of the crop variety in the field for the provided season.
  • yield_price
    Price per weight received from sale of yield.

Relationships

  • farm
    The farm that the field belongs to.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "id": "987654",
    "type": "fields",
    "links": {
      "self": "http://example.org/user_api/v1/fields/987654"
    },
    "attributes": {
      "application_cost": null,
      "area": null,
      "boundary": null,
      "chemical_cost": null,
      "contractor_cost": null,
      "created_at": "2011-06-15T10:30:00.000+08:00",
      "crops": null,
      "cropping_method": "dryland",
      "description": "Field description",
      "farm_id": 987654,
      "fertilizer_cost": null,
      "field_group_id": 987654,
      "gross_margin": null,
      "harvested_area": null,
      "harvested_weight": null,
      "harvest_date": null,
      "irrigation": "Pivot",
      "name": "Field 1",
      "other_cost": null,
      "other_income": null,
      "plant_spacing": "15 cm",
      "planting_date": null,
      "row_spacing": "20 cm",
      "season_id": null,
      "seed_cost": null,
      "updated_at": "2011-06-15T10:30:00.000+08:00",
      "yield_price": null
    },
    "relationships": {
      "farm": {
        "links": {
          "self": "http://example.org/user_api/v1/fields/987654/relationships/farm",
          "related": "http://example.org/user_api/v1/fields/987654/farm"
        }
      }
    }
  }
}

Get a field with a season specified

Many attributes such as area, are season dependant and so are only included if one is specified.

Endpoint

GET user_api/v1/fields/:id

Parameters

  • required api_token
    A valid api token to authenticate the user
  • required id
    Unique Id of the field.
  • season_id
    Unique Id of the season provided for extra seasonal field information.
  • include. farm
    INCLUDE - Sideload the farm record.

Request

Route

GET user_api/v1/fields/987654?api_token=secret&season_id=987654

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret
season_id=987654

Response

Simulated Response

Response Fields

  • id
    Unique Id of the field.
  • application_cost
    Total application costs to date for the field in the provided season.
  • area
    Area of the field for the provided season.
  • boundary
    Boundary of the field for the provided season.
  • chemical_cost
    Total chemical costs to date for the field in the provided season.
  • contractor_cost
    Total contractor costs to date for the field in the provided season.
  • created_at
    Timestamp of field creation.
  • crop_blend
    Reason for crop blend.
  • crop_grade
    Grade of the crop in the field for the provided season.
  • crop_name
    Name of the crop in the field for the provided season.
  • crop_use
    Use of the crop in the field for the provided season.
  • cropping_method
    Cropping method used in the field. e.g. dryland, irrigated.
  • description
    Description of the field.
  • fertiliser_cost
    Total fertilizer costs to date for the field in the provided season.
  • gross_margin
    Gross margin of the field for the provided season.
  • harvest_date
    Timestamp that the field has been harvested in the provided season.
  • harvested_area
    Area of the field that has been harvested in the provided season.
  • harvested_weight
    Total harvested weight for the field in the provided season.
  • irrigation
    User specified string describing irrigation method used in the field.
  • name
    Name of the field.
  • other_cost
    Total other costs to date for the field in the provided season.
  • other_income
    Total other income to date for the field in the provided season.
  • plant_spacing
    Plant spacing used in the field.
  • row_spacing
    Row spacing used in the field.
  • season_id
    Unique Id of the season provided for extra seasonal field information.
  • seed_cost
    Total seed cost to date for the field in the provided season.
  • planting_date
    Timestamp that the field has been planted in the provided season.
  • updated_at
    Timestamp of the last field update.
  • variety_name
    Name of the crop variety in the field for the provided season.
  • yield_price
    Price per weight received from sale of yield.

Relationships

  • farm
    The farm that the field belongs to.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "id": "987654",
    "type": "fields",
    "links": {
      "self": "http://example.org/user_api/v1/fields/987654"
    },
    "attributes": {
      "application_cost": "2000 dollar",
      "area": "50 ha",
      "boundary": "{\"type\":\"MultiPolygon\",\"coordinates\":[[[[171.89917,-43.71225],[171.90118,-43.71319],[171.90587,-43.70847],[171.90383,-43.70748],[171.89917,-43.71225]]]]}",
      "chemical_cost": "10000 dollar",
      "contractor_cost": "3000 dollar",
      "created_at": "2011-06-15T10:30:00.000+08:00",
      "crops": [
        {
          "crop_name": "Wheat",
          "variety_name": "Bread",
          "crop_grade": "A++",
          "crop_use": "Grain",
          "crop_blend": "primary"
        }
      ],
      "cropping_method": "dryland",
      "description": "Field description",
      "farm_id": 987654,
      "fertilizer_cost": "30000 dollar",
      "field_group_id": 987654,
      "gross_margin": "371 dollar/ha",
      "harvested_area": "50 ha",
      "harvested_weight": "150 t",
      "harvest_date": "2011-12-31T00:00:00.000+08:00",
      "irrigation": "Pivot",
      "name": "Field 1",
      "other_cost": "2500 dollar",
      "other_income": "750 dollar",
      "plant_spacing": "15 cm",
      "planting_date": "2011-01-01T00:00:00.000+08:00",
      "row_spacing": "20 cm",
      "season_id": 987654,
      "seed_cost": "2200 dollar",
      "updated_at": "2011-06-15T10:30:00.000+08:00",
      "yield_price": "450 dollar/t"
    },
    "relationships": {
      "farm": {
        "links": {
          "self": "http://example.org/user_api/v1/fields/987654/relationships/farm",
          "related": "http://example.org/user_api/v1/fields/987654/farm"
        }
      }
    }
  }
}

Listing fields

Endpoint

GET user_api/v1/fields

Parameters

  • required api_token
    A valid api token to authenticate the user
  • season_id
    Unique Id of the season provided for extra seasonal field information.
  • filter. company_id
    FILTER - The id of the company.
  • filter. farm_id
    FILTER - The id of the farm.
  • filter. name
    FILTER - The name of the field.
  • filter. updated_at
    FILTER - Return fields updated since the provided timestamp. e.g. "2011-09-12T10:30:20+08:00".
  • include. farm
    INCLUDE - Sideload the farm record.

Request

Route

GET user_api/v1/fields?api_token=secret

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret

Response

Simulated Response

Response Fields

  • id
    Unique Id of the field.
  • application_cost
    Total application costs to date for the field in the provided season.
  • area
    Area of the field for the provided season.
  • boundary
    Boundary of the field for the provided season.
  • chemical_cost
    Total chemical costs to date for the field in the provided season.
  • contractor_cost
    Total contractor costs to date for the field in the provided season.
  • created_at
    Timestamp of field creation.
  • crop_blend
    Reason for crop blend.
  • crop_grade
    Grade of the crop in the field for the provided season.
  • crop_name
    Name of the crop in the field for the provided season.
  • crop_use
    Use of the crop in the field for the provided season.
  • cropping_method
    Cropping method used in the field. e.g. dryland, irrigated.
  • description
    Description of the field.
  • fertiliser_cost
    Total fertilizer costs to date for the field in the provided season.
  • gross_margin
    Gross margin of the field for the provided season.
  • harvest_date
    Timestamp that the field has been harvested in the provided season.
  • harvested_area
    Area of the field that has been harvested in the provided season.
  • harvested_weight
    Total harvested weight for the field in the provided season.
  • irrigation
    User specified string describing irrigation method used in the field.
  • name
    Name of the field.
  • other_cost
    Total other costs to date for the field in the provided season.
  • other_income
    Total other income to date for the field in the provided season.
  • plant_spacing
    Plant spacing used in the field.
  • row_spacing
    Row spacing used in the field.
  • season_id
    Unique Id of the season provided for extra seasonal field information.
  • seed_cost
    Total seed cost to date for the field in the provided season.
  • planting_date
    Timestamp that the field has been planted in the provided season.
  • updated_at
    Timestamp of the last field update.
  • variety_name
    Name of the crop variety in the field for the provided season.
  • yield_price
    Price per weight received from sale of yield.

Relationships

  • farm
    The farm that the field belongs to.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": [
    {
      "id": "987654",
      "type": "fields",
      "links": {
        "self": "http://example.org/user_api/v1/fields/987654"
      },
      "attributes": {
        "application_cost": null,
        "area": null,
        "boundary": null,
        "chemical_cost": null,
        "contractor_cost": null,
        "created_at": "2011-06-15T10:30:00.000+08:00",
        "crops": null,
        "cropping_method": "dryland",
        "description": "Field description",
        "farm_id": 987654,
        "fertilizer_cost": null,
        "field_group_id": 987654,
        "gross_margin": null,
        "harvested_area": null,
        "harvested_weight": null,
        "harvest_date": null,
        "irrigation": "Pivot",
        "name": "Field 1",
        "other_cost": null,
        "other_income": null,
        "plant_spacing": "15 cm",
        "planting_date": null,
        "row_spacing": "20 cm",
        "season_id": null,
        "seed_cost": null,
        "updated_at": "2011-06-15T10:30:00.000+08:00",
        "yield_price": null
      },
      "relationships": {
        "farm": {
          "links": {
            "self": "http://example.org/user_api/v1/fields/987654/relationships/farm",
            "related": "http://example.org/user_api/v1/fields/987654/farm"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://example.org/user_api/v1/fields?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10",
    "last": "http://example.org/user_api/v1/fields?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10"
  }
}

Listing fields with a season specified

Many attributes such as area, are season dependant and so are only included if one is specified.

Endpoint

GET user_api/v1/fields

Parameters

  • required api_token
    A valid api token to authenticate the user
  • season_id
    Unique Id of the season provided for extra seasonal field information.
  • filter. company_id
    FILTER - The id of the company.
  • filter. farm_id
    FILTER - The id of the farm.
  • filter. name
    FILTER - The name of the field.
  • filter. updated_at
    FILTER - Return fields updated since the provided timestamp. e.g. "2011-09-12T10:30:20+08:00".
  • include. farm
    INCLUDE - Sideload the farm record.

Request

Route

GET user_api/v1/fields?api_token=secret&season_id=987654

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret
season_id=987654

Response

Simulated Response

Response Fields

  • id
    Unique Id of the field.
  • application_cost
    Total application costs to date for the field in the provided season.
  • area
    Area of the field for the provided season.
  • boundary
    Boundary of the field for the provided season.
  • chemical_cost
    Total chemical costs to date for the field in the provided season.
  • contractor_cost
    Total contractor costs to date for the field in the provided season.
  • created_at
    Timestamp of field creation.
  • crop_blend
    Reason for crop blend.
  • crop_grade
    Grade of the crop in the field for the provided season.
  • crop_name
    Name of the crop in the field for the provided season.
  • crop_use
    Use of the crop in the field for the provided season.
  • cropping_method
    Cropping method used in the field. e.g. dryland, irrigated.
  • description
    Description of the field.
  • fertiliser_cost
    Total fertilizer costs to date for the field in the provided season.
  • gross_margin
    Gross margin of the field for the provided season.
  • harvest_date
    Timestamp that the field has been harvested in the provided season.
  • harvested_area
    Area of the field that has been harvested in the provided season.
  • harvested_weight
    Total harvested weight for the field in the provided season.
  • irrigation
    User specified string describing irrigation method used in the field.
  • name
    Name of the field.
  • other_cost
    Total other costs to date for the field in the provided season.
  • other_income
    Total other income to date for the field in the provided season.
  • plant_spacing
    Plant spacing used in the field.
  • row_spacing
    Row spacing used in the field.
  • season_id
    Unique Id of the season provided for extra seasonal field information.
  • seed_cost
    Total seed cost to date for the field in the provided season.
  • planting_date
    Timestamp that the field has been planted in the provided season.
  • updated_at
    Timestamp of the last field update.
  • variety_name
    Name of the crop variety in the field for the provided season.
  • yield_price
    Price per weight received from sale of yield.

Relationships

  • farm
    The farm that the field belongs to.

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": [
    {
      "id": "987654",
      "type": "fields",
      "links": {
        "self": "http://example.org/user_api/v1/fields/987654"
      },
      "attributes": {
        "application_cost": "2000 dollar",
        "area": "50 ha",
        "boundary": "{\"type\":\"MultiPolygon\",\"coordinates\":[[[[171.89917,-43.71225],[171.90118,-43.71319],[171.90587,-43.70847],[171.90383,-43.70748],[171.89917,-43.71225]]]]}",
        "chemical_cost": "10000 dollar",
        "contractor_cost": "3000 dollar",
        "created_at": "2011-06-15T10:30:00.000+08:00",
        "crops": [
          {
            "crop_name": "Wheat",
            "variety_name": "Bread",
            "crop_grade": "A++",
            "crop_use": "Grain",
            "crop_blend": "primary"
          }
        ],
        "cropping_method": "dryland",
        "description": "Field description",
        "farm_id": 987654,
        "fertilizer_cost": "30000 dollar",
        "field_group_id": 987654,
        "gross_margin": "371 dollar/ha",
        "harvested_area": "50 ha",
        "harvested_weight": "150 t",
        "harvest_date": "2011-12-31T00:00:00.000+08:00",
        "irrigation": "Pivot",
        "name": "Field 1",
        "other_cost": "2500 dollar",
        "other_income": "750 dollar",
        "plant_spacing": "15 cm",
        "planting_date": "2011-01-01T00:00:00.000+08:00",
        "row_spacing": "20 cm",
        "season_id": 987654,
        "seed_cost": "2200 dollar",
        "updated_at": "2011-06-15T10:30:00.000+08:00",
        "yield_price": "450 dollar/t"
      },
      "relationships": {
        "farm": {
          "links": {
            "self": "http://example.org/user_api/v1/fields/987654/relationships/farm",
            "related": "http://example.org/user_api/v1/fields/987654/farm"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://example.org/user_api/v1/fields?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10",
    "last": "http://example.org/user_api/v1/fields?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10"
  }
}

Seasons

Get a season

Endpoint

GET /user_api/v1/seasons/:id

Parameters

  • required api_token
    A valid api token to authenticate the user
  • required id
    Unique ID of the season.

Request

Route

GET /user_api/v1/seasons/987656?api_token=secret

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret

Response

Simulated Response

Response Fields

  • id
    Unique ID of the season.
  • approved
    Returns true if the season is approved or false if the season is a draft.
  • company_id
    ID of the company that the season belongs to.
  • created_at
    Timestamp of season creation.
  • name
    Name of the season.
  • season_end_date
    Timestamp of the season end date.
  • season_start_date
    Timestamp of the season start date.
  • updated_at
    Timestamp of the last season update.

Relationships

  • companies
    The company that the seasons belongs to.
  • fields
    Fields belonging to this season
  • activities
    Activities belonging to this season

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "id": "987656",
    "type": "seasons",
    "links": {
      "self": "http://example.org/user_api/v1/seasons/987656"
    },
    "attributes": {
      "approved": null,
      "company_id": 987656,
      "created_at": "2011-06-15T10:30:00.000+08:00",
      "name": "2016",
      "season_end_date": "2011-12-31",
      "season_start_date": "2011-01-01",
      "updated_at": "2011-06-15T10:30:00.000+08:00"
    },
    "relationships": {
      "company": {
        "links": {
          "self": "http://example.org/user_api/v1/seasons/987656/relationships/company",
          "related": "http://example.org/user_api/v1/seasons/987656/company"
        }
      },
      "fields": {
        "links": {
          "self": "http://example.org/user_api/v1/seasons/987656/relationships/fields",
          "related": "http://example.org/user_api/v1/seasons/987656/fields"
        }
      },
      "activities": {
        "links": {
          "self": "http://example.org/user_api/v1/seasons/987656/relationships/activities",
          "related": "http://example.org/user_api/v1/seasons/987656/activities"
        }
      }
    }
  }
}

Listing seasons

Endpoint

GET /user_api/v1/seasons

Parameters

  • required api_token
    A valid api token to authenticate the user
  • filter. company_id
    FILTER - ID of the company that the season belongs to.
  • filter. name
    FILTER - Name of the season.
  • filter. updated_at
    FILTER - Return seasons updated since the provided timestamp. e.g. "2011-09-12T10:30:20+08:00".

Request

Route

GET /user_api/v1/seasons?api_token=secret&filter[name]=2016

Headers

Content-Type: application/vnd.api+json

Query Parameters

api_token=secret
filter={"name"=>"2016"}

Response

Simulated Response

Response Fields

  • id
    Unique ID of the season.
  • approved
    Returns true if the season is approved or false if the season is a draft.
  • company_id
    ID of the company that the season belongs to.
  • created_at
    Timestamp of season creation.
  • name
    Name of the season.
  • season_end_date
    Timestamp of the season end date.
  • season_start_date
    Timestamp of the season start date.
  • updated_at
    Timestamp of the last season update.

Relationships

  • companies
    The company that the seasons belongs to.
  • fields
    Fields belonging to this season
  • activities
    Activities belonging to this season

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": [
    {
      "id": "987656",
      "type": "seasons",
      "links": {
        "self": "http://example.org/user_api/v1/seasons/987656"
      },
      "attributes": {
        "approved": null,
        "company_id": 987656,
        "created_at": "2011-06-15T10:30:00.000+08:00",
        "name": "2016",
        "season_end_date": "2011-12-31",
        "season_start_date": "2011-01-01",
        "updated_at": "2011-06-15T10:30:00.000+08:00"
      },
      "relationships": {
        "company": {
          "links": {
            "self": "http://example.org/user_api/v1/seasons/987656/relationships/company",
            "related": "http://example.org/user_api/v1/seasons/987656/company"
          }
        },
        "fields": {
          "links": {
            "self": "http://example.org/user_api/v1/seasons/987656/relationships/fields",
            "related": "http://example.org/user_api/v1/seasons/987656/fields"
          }
        },
        "activities": {
          "links": {
            "self": "http://example.org/user_api/v1/seasons/987656/relationships/activities",
            "related": "http://example.org/user_api/v1/seasons/987656/activities"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://example.org/user_api/v1/seasons?filter%5Bname%5D=2016\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=10",
    "last": "http://example.org/user_api/v1/seasons?filter%5Bname%5D=2016\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=10"
  }
}