KisanHub logo
API docs by Redocly

KisanHub API (1.0)

Download OpenAPI specification:Download

API Support: support@kisanhub.com

Introduction

Welcome to the KisanHub developer space! You'll find comprehensive guides and documentation to help you start working with KisanHub as quickly as possible, as well as support if you get stuck.

KisanHub is a supply management platform that brings complex agricultural and procurement data together in one convenient platform so you can better predict supply and make the most of demand.

If you have any questions, please get in touch with our team support@kisanhub.com

Authentication

KisanHub uses Bearer Authentication (also called token authentication). You must include an Authorization header when making requests to the API:

Authorization: Token <token>

Please contact support@kisanhub.com to obtain your API token. All API calls should end with a trailing /: you'll get 301 error codes if you forget this.

Units

All date-times are UTC and in RFC3339 format, although most APIs also accept simple dates without the time component (in YYYY-MM-DD format).

We use metric units throughout e.g we use hectares for area.

Language

Some APIs will return localised names where available, in response to the ACCEPT_LANGUAGE header. Note that we only use the first (language) part of the header value: e.g en-US will be converted to en. The language may also be overridden via the language query parameter for convenience. Note that at the moment the only available languages are:

  • en (English)
  • hi (Hindi)
  • mr (Marathi)

Common filters

GET APIs will be default return all information associated with the requested entity. You can retrict the fields returned by using the only query parameter. For example:

https://api.kisanhub.com/api/field/?only=id,farm_id

Glossary

The Agritech industry as a whole uses a lot of terms in often conflicting and ambiguous ways. At KisanHub we've tried to come up with a standardised set of terms that we use throughout our platform, which should mostly map onto the terms you're expecting.

Term Our meaning
User A user of the KisanHub platform.
Team A grouping of users, often mapped to an organisation
Organisation An organisation is a named legal entity. There is a 1-1 mapping between organisation and team
Site A deprecated grouped of teams. Generally the site was associated a single KisanHub enterprise customer
Farm A hub from which a collection of fields are managed. A team can have one or many farms, and controls access to the fields and related data
Field A geographical region of land owned by a Farm that can be used to grow crops.
Plot A subsection of a Field which is to be (or has already been) planted with a single crop.
Observation An observation on a plot e.g ground cover. Observation is also called 'Crop Monitoring'
Product A product that can be applied to a plot e.g pesticide, fertiliser
Genus The genus of the planted crop e.g "Potato". Note that historically this was known as a Crop, and is still referred to as such in some older APIs (e.g crop_id)
Variety The variety of the planted crop e.g "Adora"
PestDisease A general term and encompasses all pests and diseases that can afflict a crop
Primary Growth Stage A broad stage in the lifecycle of a crop, for example germination.
Secondary Growth Stage Represents a more granular metric of where a given crop is in it's Primary Growth Stage development.
Store A physical building owned by an organisation that can be used to store crop.
Store Lot StoreLot is the fraction of the store that contains, or will contain, an amount from the crop.
Customer The customer is the organisation who is paying for the produce in a transaction
Load A load is a transaction with a supplier/seller, a customer/buyer, and a crop
Trade Record A record of a load transaction that is sent to the customer and verified at intake
Trading Agreement A sales or purchase contract between two organisations
Load Ticket Another (deprecated) name for trade record
Off-platform An "off-platform" field or plot is one that is recorded on the platform but is not actively managed by us. Off-platform fields and plots have no polygons and so do not appear on the geojson APIs, but can otherwise be used as normal
Operation An operation on a plot e.g planting, harvest. An operation may either be planned or applied
Operation schedule A schedule of planned operations that can be created automatically after a specified trigger

Permissions

The following permission levels determine the actions and data that is available to the user:

Permission Description
REGISTRATION_ADMIN Registration admins can access and edit teams/users/farms and fields under their Site
CROP_QUALITY_ADMIN Allows creation and edit of crop quality templates
SITE_ADMIN DEPRECATED. Site admins can access and edit teams/users/farms/fields/plots under their Site

PUT operations

When an API accepts a PUT request the object is not replaced it is updated. Only the attributes present in the request will be altered: default values will not be set for attributes that are absent from the request. As such you should pass in the entire object in the payload unless you want the PUT to behave like a PATCH.

User

User management

List users

Returns details for all visible users. In practise this will return the details for all users in all visible teams, so the same visibility rules for teams apply here. To recap: all users will be able to see their own teammates plus the details of all users in teams which have shared one or more plots with their team.

Users with SITE_ADMIN or REGISTRATION_ADMIN permission will in additional see users for all teams associated with their Site.

Kisanhub staff members can see all users regardless.

  • All user
  • Kisanhub staff can see all users
  • Users with either the SITE_ADMIN or will be able to view all users associated with their Site
  • A user can always view users from their team connected teams with can_manage flag
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

organisation_id
integer >= 1
Example: organisation_id=1

Filter by the organisation ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

email
string

Only return users with this email address

phone
string

Only return users with this phone number

search
string

Text search - checks first_name, last_name, email and phone_number

user_type
string
Enum: "grower" "agronomist"

Filter on the user type

include_collaborators
boolean
Deprecated
Default: false

This used to force the inclusion of users from teams which have shared plots. However that is now the default behaviour, so this has no effect and is ignored.

permission
string
Enum: "staff" "crop_quality_admin" "registration_admin"

Filter users with the specified permission

sort_field
string
Enum: "id" "name" "last_access"

Determine the sort field of returned users. Note that name sorts by first_name then last_name

sort_direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction

state
string
Default: "active"
Enum: "active" "inactive"

Filter by active or inactive user state. We will default to only returning active users

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create user

Create a new user. A user with TEAM_ADMIN may create users for their own team. An Enterprise user with SITE_ADMIN permission may create users for any of their client teams. A Kisanhub staff user may create users for any teams.

Request Body schema: application/json
username
required
string

Globally unique username. This should be the either the supplied phone number or the email address

first_name
required
string

First (and middle) name

last_name
required
string

Last name

email
string

Email

is_active
boolean

Is this an active user?

team_id
integer

Primary team key

organisation_id
integer

Organisation ID

object (ContactDetails)

Contact details

object (UserDemographics)

Demographical user information

object (GrowerDetails)
Address (object) or LegacyAddress (object) (schemas-Address)

User address. Please use the newer Address schema

object (Permissions)
last_access
string <date-time>

Date-time when this user last accessed the KisanHub platform via an API call

password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Get user

Return a single user. A user with TEAM_ADMIN permission may access any users within their team. An Enterprise user with SITE_ADMIN permission view users in any of their client teams. A Kisanhub staff user may view any user.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Update user

Update an existing user. A user should always be able to update their own details. A user with TEAM_ADMIN permission may update any user within their own team. An Enterprise user with SITE_ADMIN permission may update any user in any of their client teams. A Kisanhub staff user may update any user in any team.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Request Body schema: application/json
username
required
string

Globally unique username. This should be the either the supplied phone number or the email address

first_name
required
string

First (and middle) name

last_name
required
string

Last name

email
string

Email

is_active
boolean

Is this an active user?

team_id
integer

Primary team key

organisation_id
integer

Organisation ID

object (ContactDetails)

Contact details

object (UserDemographics)

Demographical user information

object (GrowerDetails)
Address (object) or LegacyAddress (object) (schemas-Address)

User address. Please use the newer Address schema

object (Permissions)
last_access
string <date-time>

Date-time when this user last accessed the KisanHub platform via an API call

Responses

Request samples

Content type
application/json
{
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Partial user update

Partially update an existing user

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Request Body schema: application/json
username
required
string

Globally unique username. This should be the either the supplied phone number or the email address

first_name
required
string

First (and middle) name

last_name
required
string

Last name

email
string

Email

is_active
boolean

Is this an active user?

team_id
integer

Primary team key

organisation_id
integer

Organisation ID

object (ContactDetails)

Contact details

object (UserDemographics)

Demographical user information

object (GrowerDetails)
Address (object) or LegacyAddress (object) (schemas-Address)

User address. Please use the newer Address schema

object (Permissions)
last_access
string <date-time>

Date-time when this user last accessed the KisanHub platform via an API call

Responses

Request samples

Content type
application/json
{
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Reactivate user

Reactivate a user. A non-staff user may only reactivate users in their own team or in teams that they manage

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Deactivate user

Deactivate the user. A non-staff user may only deactivate users in their own team or in teams that they manage. You cannot deactivate your own user.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

User ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "username": "me@you.com",
  • "first_name": "Bob",
  • "last_name": "Smith",
  • "email": "me@you.com",
  • "is_active": true,
  • "team_id": 5,
  • "organisation_id": 7,
  • "organisation_name": "Big Corp",
  • "contact_details": {
    },
  • "demographics": {
    },
  • "grower_details": {
    },
  • "address": {
    },
  • "permissions": {
    },
  • "last_access": "2019-08-24T14:15:22Z"
}

Validate new user

Checks whether the specified password or phone number is valid for a new user

query Parameters
phone
string

Phone number to be checked

email
string

email to be checked

Responses

Response samples

Content type
application/json
{
  • "email": "string",
  • "phone": "string"
}

Invite users

Invite one or more users by email to an organisation.

While any user may invite a user to their own organisation, permission to invite to another organisation is restricted by the following rules:

  • KisanHub staff may invite to any organisation
  • Users with registration_admin access may invite users to organisations that they are managing

Only KisanHub staff may set the is_staff or registration_admin permission, and only registration admins may set the crop_quality_admin flag.

Request Body schema: application/json
organisation_id
integer

Organisation ID. If not specified then assume the user's own organisation.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "organisation_id": 7,
  • "users": [
    ]
}

Verify invite token

Verify a user invite token and return details about the inviter

path Parameters
token
required
string

Token generated as a result of the user invite

Responses

Response samples

Content type
application/json
{
  • "inviter_user_name": "string",
  • "inviter_organisation_name": 0,
  • "target_organisation_name": 0
}

Create user from invite

Create a new user using an invite token

path Parameters
token
required
string

Token generated as a result of the user invite

Request Body schema: application/json
first_name
required
string

First name

last_name
required
string

Last name

phone_number
string

Phone number (preferably mobile)

password
required
string

The desired password

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "user_id": 0,
  • "username": "string",
  • "email": "string",
  • "organisation_id": 0,
  • "team_id": 0,
  • "first_name": "string",
  • "last_name": "string",
  • "features": [
    ],
  • "permissions": [
    ],
  • "is_staff": true
}

Request password reset

Request to reset an account's password via email.

Request Body schema: application/json
email
string

The email address of the account.

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Set password

Set a new account password.

Request Body schema: application/json
uid
required
integer

User ID of the account.

password
required
string

The desired password for the account.

token
required
string

The generated token used to verify the password reset.

Responses

Request samples

Content type
application/json
{
  • "uid": 0,
  • "password": "string",
  • "token": "string"
}

List allowed features Deprecated

List of allowed dashboard applications. DEPRECATED in favour of /api/account/access

Responses

Response samples

Content type
application/json
[
  • "myfarm",
  • "registration"
]

Get user access Deprecated

Returns all available features and permission levels for the requesting user. DEPRECATED in favour of /api/profile

Responses

Response samples

Content type
application/json
{
  • "features": [
    ],
  • "permissions": [
    ]
}

List user training

Returns a list of training events attended by the given user

path Parameters
user_id
required
integer >= 1

id of the user whose training data should be fetched

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

year
integer

Year of the training when it was conducted

status
string
Default: "attended"
Enum: "attended" "absent" "registered"

Status of the user registration for a training

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Get user profile

Returns user profile information which includes team, organisation, name and all available features and permission levels for the requesting user

Responses

Response samples

Content type
application/json
{
  • "user_id": 0,
  • "username": "string",
  • "email": "string",
  • "organisation_id": 0,
  • "team_id": 0,
  • "first_name": "string",
  • "last_name": "string",
  • "features": [
    ],
  • "permissions": [
    ],
  • "is_staff": true
}

User team selection

A list of selected team summaries, mainly used so we can deliver relevant notifications.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

User team selection

A list of selected team IDs, mainly used so we can deliver relevant notifications.

Request Body schema: application/json
selected_team_ids
required
Array of integers

A list of selected team IDs.

Responses

Request samples

Content type
application/json
{
  • "selected_team_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "selected_team_ids": [
    ]
}

Submit feedback

Submit feedback on app functionality for our team to review

Request Body schema: application/json
comment
string

Comment to include with the user feedback (max 500 characters)

image
string

Screenshot of the associated page user is giving feedback for

star_rating
integer

Rating of the page, from 1 to 5

url
string

URL of the page the user is giving feedback for

submitted_by
integer

ID of the user submitting the feedback

submitted_at
string <date-time>

Datetime of submission - defaults to now

permission_to_contact
boolean

Whether the user is happy to be contacted about this feedback

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "image": "string",
  • "star_rating": 0,
  • "url": "string",
  • "submitted_by": 0,
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "permission_to_contact": true
}

Response samples

Content type
application/json
{
  • "comment": "string",
  • "image": "string",
  • "star_rating": 0,
  • "url": "string",
  • "submitted_by": 0,
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "permission_to_contact": true
}

Team

A team is a group of users: a user can belong to a single team.

Return a list of Teams

Returns a list of all teams for which the user is currently able to view any Plots or Storelots. A Team is added to the list if any of the following conditions are met:

  • The user is in the team
  • The organisation I am part of is connected to the organisation belonging to the team
  • An open plot that is owned by the team is visible to the users team. This could be because the user's team owns the plot, or because the plot has been shared with the user's team.
  • An open storelot that is owned by the team is visible to the user's team. This could be because the user's team created the storelot, grew the plot from which the storelot came, or shared the plot from which the storelot came with the user's team
  • The user has either SITE_ADMIN or REGISTRATION_ADMIN permission and has the same Site as the target Team
  • The user is KisanHub staff
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

page_size
integer [ 0 .. 100 ]
Default: 20

Page size. Use "0" for all results in a single page

search
string

Search for team by name

exclude_plot_shares
boolean
Default: false

Returns the team to which the user belongs.

only_plot_shares
boolean
Default: false

If true then only include teams that own Plots which are open & visible to the user; either because they belong to the user's team, or because they have been shared with the user's team.

only_storelot_shares
boolean
Default: false

If true then only include teams that own Storelots which are open & visible to the user; either because they belong to the user's team, or because they have been shared with the user's team.

only_shares
boolean
Default: false

If true then only include teams that own either Plots or Storelots which are open & visible to the user. This is already the default response for most users. This option is relevant to users with admin permissions and allows them to ignore their admin permissions and see only the teams from which data has been shared with them.

site_id
integer

Filters by Site ID

integration
string

Get all the teams who have subscribed to this integration

exclude_shared_with_plot
integer

Exclude any teams that this specific plot has been shared with.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create a new Team

Create a new Team. Only Kisanhub staff and enterprise users with SITE_ADMIN permission will be allowed to create teams.

Request Body schema: application/json
name
string

Team name

slug
string
Deprecated

Legacy identifier

site_id
integer
Deprecated

Teams are associated with a parent "Site". This is a legacy concept which will be replaced with a full organisational structure shortly.

global_gap_id
string

Global gap id of the lead user.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "slug": "string",
  • "site_id": 0,
  • "global_gap_id": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "slug": "string",
  • "lead": 1,
  • "site_id": 0,
  • "global_gap_id": "string",
  • "organisation_id": 1
}

Get team

Accessible teams will depend on the access rights of the requesting user. A user will always be able to view their own team, and teams that have shared plots with them. A user with the SITE_ADMIN permission in an Enterprise team will be able to view users of client teams. A Kisanhub staff member will be able to view all teams.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Team ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "slug": "string",
  • "lead": 1,
  • "site_id": 0,
  • "global_gap_id": "string",
  • "organisation_id": 1
}

Update an existing Team

Note that the team name must be globally unique

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Team ID

Request Body schema: application/json
name
string

Team name

slug
string
Deprecated

Legacy identifier

site_id
integer
Deprecated

Teams are associated with a parent "Site". This is a legacy concept which will be replaced with a full organisational structure shortly.

global_gap_id
string

Global gap id of the lead user.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "slug": "string",
  • "site_id": 0,
  • "global_gap_id": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "slug": "string",
  • "lead": 1,
  • "site_id": 0,
  • "global_gap_id": "string",
  • "organisation_id": 1
}

List team directory

Paginated list of all the teams in platform.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string"
}

Get team directory.

Summary of team from team directory.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Team ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string"
}

Farm

A farm in KisanHub owns a set of fields. It has a geographic location and an address, and is owned by a single team.

The following rules determine whether a particular user can edit or delete a farm:

  • The farm is owned by their team
  • The user has SITE_ADMIN permission and the team is associated with their Site
  • The user is a KisanHub staff member

A user can view a farm if any of the above rules are satisfied, or if one or more plots from fields in the farm have been shared with the user or their team.

List farms

Return a list of farms. A farm is included in the list if any of the following conditions are met:

  • The user is in the same team as the farm
  • The user's team is connected and can manage the farm team
  • The user originally created the Farm (e.g on behalf of a third party)
  • A plot from any fields owned by the farm has been shared with the users team, unless the exclude_plot_shares query parameter is set to "true"
  • The user is KisanHub staff
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

search
string
Example: search=my-plot

Text search

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

created_by_id
integer >= 1
Example: created_by_id=1

Filter by the user ID who created these entities

exclude_no_plots
boolean
Default: false

If true then exclude farms which have shared plots

exclude_plot_shares
boolean
Default: false

If true then exclude farms that are only visible due to Plot sharing

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create farm

Create a new farm. A team user with TEAM_ADMIN permission will be able to create a farm for their team. An enterprise user with SITE_ADMIN permission will be able to create a farm for a client team. A Kisanhub staff member can create farms for any team.

Request Body schema: application/json
name
required
string

Farm name

object (components-schemas-Address)
location
required
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

notes
string

Any notes related to the farm

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": {
    },
  • "location": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "slug": "string",
  • "name": "string",
  • "team_id": 1,
  • "address": {
    },
  • "location": [
    ],
  • "access": "read-edit",
  • "notes": "string",
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Deleted farms since a given date

List farm ids which have been deleted since a given date

query Parameters
from_date
required
string <date-time>

Include deleted farms from this date

Responses

Response samples

Content type
application/json
[
  • 0
]

GeoJSON farms

Farm summaries in GeoJSON format

query Parameters
team_id
integer >= 1
Example: team_id=42

Filter by the team ID

season
string
Deprecated
Example: season=2019/20

Growing season

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Get farm

Return a single farm by ID

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "slug": "string",
  • "name": "string",
  • "team_id": 1,
  • "address": {
    },
  • "location": [
    ],
  • "access": "read-edit",
  • "notes": "string",
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete farm

Delete a farm. Only farms with no attached fields can be deleted: an attempt to delete a farm with existing fields will result in a 409 error code.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Update farm

Update an existing farm. A team user with TEAM_ADMIN permission will be able to update a farm if it is owned by their team. An enterprise user with SITE_ADMIN permission will be able to update a farm for a client team. A Kisanhub staff member can update any farm.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Farm ID

Request Body schema: application/json
name
required
string

Farm name

object (components-schemas-Address)
location
required
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

notes
string

Any notes related to the farm

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": {
    },
  • "location": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "slug": "string",
  • "name": "string",
  • "team_id": 1,
  • "address": {
    },
  • "location": [
    ],
  • "access": "read-edit",
  • "notes": "string",
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get farm permission

Returns the permission level for this farm. A user has read/write access to a farm if any of the following conditions are met:

  • They are in the same Team as the Farm
  • The user has SITE_ADMIN or REGISTRATION_ADMIN access to the same Site as the Farm
  • The user is KisanHub staff

The user has read-only access to a farm only if they have access to any of the plots contained by any fields owned by this farm, and none of the above conditions apply.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "access": "read-edit",
  • "noDeleteReason": "string"
}

Field

A field corresponds to a bounded area of land that will be used to grow crops. In general fields are unchanged over time, since they represent real physical boundaries. A field will contain one or more plots.

List fields

Return a list of fields. The accessible fields depends on the request user permissions:

  • Kisanhub staff can see all fields
  • Farm owners (i.e users in the Team that owns the farm) can see all the farm fields
  • Users can see fields containing plots that have been shared with them or created by them
  • Users can see fields of connected manageable teams
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

organisation_id
integer >= 1
Example: organisation_id=1

Filter by the organisation ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

search
string
Example: search=my-plot

Text search

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

created_by_id
integer >= 1
Example: created_by_id=1

Filter by the user ID who created these entities

off_platform
string
Enum: "only" "exclude"

If only then only returns "off-platform" fields· If exclude then exclude "off-platform" fields. If not specified then fields of both types are returned.

has_active_plots
boolean
Example: has_active_plots=true

If set then only include fields which have any active plots

genus_id
integer >= 1
Example: genus_id=2

Only include fields that have plots growing this genus

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create field

Create a new field. If a team user with TEAM_ADMIN can create fields for their own farm. An enterprise user with SITE_ADMIN permission may create fields for a farms owned by any of their client teams. A Kisanhub staff member may create a field for any farm.

Request Body schema: application/json
farm_id
required
integer >= 1

Farm ID if owned by a farm (i.e is "on-platform")

organisation_id
integer >= 1

Organisation ID if this is an off-platform field owned by an organisation

name
required
string

Field name

government_id
string

Governmental field identifier

soil_type_id
required
integer >= 1

Primary key

object (Boundary)

Bounding polygon

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

notes
string

Any notes related to the field

noDeleteReason
string

Describes why the entity cannot be deleted (usually because it contains other entities)

Responses

Request samples

Content type
application/json
{
  • "farm_id": 1,
  • "organisation_id": 1,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "boundary": {
    },
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "id": 1,
  • "slug": "string",
  • "access": "read-edit",
  • "farm_id": 1,
  • "organisation_id": 1,
  • "team_id": 0,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "region": "string",
  • "country_code": "st",
  • "boundary": {
    },
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Deleted fields since a given date

List field ids which have been deleted since a given date

query Parameters
from_date
required
string <date-time>

Include deleted fields from this date

Responses

Response samples

Content type
application/json
[
  • 0
]

Get field

Return a field

path Parameters
id
required
integer >= 1

Field primary key

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "id": 1,
  • "slug": "string",
  • "access": "read-edit",
  • "farm_id": 1,
  • "organisation_id": 1,
  • "team_id": 0,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "region": "string",
  • "country_code": "st",
  • "boundary": {
    },
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Delete field

Delete a field. Only fields with no attached plots can be deleted: an attempt to delete a field with any existing plots (including closed plots) will result in a 409 error code.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Update field

Update an existing field. If a team user with TEAM_ADMIN can update fields for their own farm. An enterprise user with SITE_ADMIN permission may update fields for a farms owned by any of their client teams. A Kisanhub staff member may update any field in any farm.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
farm_id
required
integer >= 1

Farm ID if owned by a farm (i.e is "on-platform")

organisation_id
integer >= 1

Organisation ID if this is an off-platform field owned by an organisation

name
required
string

Field name

government_id
string

Governmental field identifier

soil_type_id
required
integer >= 1

Primary key

object (Boundary)

Bounding polygon

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

notes
string

Any notes related to the field

noDeleteReason
string

Describes why the entity cannot be deleted (usually because it contains other entities)

Responses

Request samples

Content type
application/json
{
  • "farm_id": 1,
  • "organisation_id": 1,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "boundary": {
    },
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_id": 1,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by_id": 1,
  • "id": 1,
  • "slug": "string",
  • "access": "read-edit",
  • "farm_id": 1,
  • "organisation_id": 1,
  • "team_id": 0,
  • "name": "string",
  • "government_id": "string",
  • "soil_type_id": 1,
  • "region": "string",
  • "country_code": "st",
  • "boundary": {
    },
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "notes": "string",
  • "noDeleteReason": "string"
}

Get field permission

Returns the permission level for this field. A user has read/write access to a field if any of the following conditions are met:

  • They are in the same Team as the parent Farm
  • The user has SITE_ADMIN or REGISTRATION_ADMIN access to the same Site as the Farm
  • The user is KisanHub staff

The user has read-only access to a field only if they have access to any of the plots contained by the field, but none of the above conditions.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "access": "read-edit",
  • "noDeleteReason": "string"
}

List GeoJSON fields

Field summaries in GeoJSON format

query Parameters
team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

season
string
Deprecated
Example: season=2019/20

Growing season

bounds
Array of integers[ items = 4 characters ]
Example: bounds=-0.6287,53.8621,-0.5636,53.8830

Only return features that are contained within the bounding box (including intersects)

Format is xMin,yMin,xMax,yMax (i.e lng,lat NW / SE)

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Upload shapefile

Upload a ESRI GIS zipped field boundary shapefile

Request Body schema: multipart/form-data
file
string <binary>

Zipped ESRI shapefiles

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "names": [
    ]
}

Import shapefile

Creates fields for each polygon found in the ESRI zipped shapefile previously uploaded using the /api/field/shapefile/upload endpoint. Fields are added to a single Farm. This is an asynchronous operation: the caller can use /api/field/shapefile/import/{upload_id}/status to poll for status.

path Parameters
farm_id
required
integer >= 1

Farm primary key

upload_id
required
integer >= 1

ID of previously uploaded shapefile (returned from /api/field/shapefile/upload)

query Parameters
name_property
string
Default: "Name"

Use this property as the field name

Responses

Get shapefile upload status

path Parameters
upload_id
required
integer >= 1

ID of previously uploaded shapefile (returned from /api/field/shapefile/upload)

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "total": 0,
  • "completed": 0,
  • "errors": [
    ]
}

Plot

A plot describes a subdivision of a field that is planted with a particular crop variety. While this is modelled independently to operations the lifecycle of a plot is intimately connected with it's sowing and harvest operations. As such this API doesn't quite follow the same design pattern as elsewhere, since it allows the modification of sowing and harvest information: adding a planned or actual planting date will result in a new sowing operation being created, and similarly adding the planned or actual harvest date or yield will result in a new harvest operation being created (see operations). Editing existing dates and yields will edit the existing operation.

A planned sowing operation will be created by default for a new plot with the specified genus, variety and planting area. Todays date (with 00:00 time component) is taken as the start_date unless planned_planting_date is provided.

Plot operations can also be created and updated via operation API.

Plots can be shared/unshared with collaborating teams via the team-shares API. Only the team which own the plot, or the team of the owning plot (where they have allow_edit: true on their team-share) have the ability to share plots, no onward sharing past this is possible.

List plots

Return a paginated list of plots. By default we only return active plots i.e plots that have not been closed - use the "state" parameter to override this behaviour.

The plots that are accessible by the caller depends on a number of factors. Specifically a plot is visible for a user if any of the following conditions are met:

  • It is in the same team as the calling user (i.e the parent farm is in the same team as the caller)
  • The calling user is in the same team as the user that created the plot initially
  • The plot has explicitly been shared with the request user's team
  • The plot is associated with a existing trade record that is visible to the user
  • The caller has SITE_ADMIN permission and the plot is in a farm, owned by a Team associated with their Site
  • The caller is a KisanHub staff member
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

group_id
integer >= 1
Example: group_id=43

Filter by the organisation group ID

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

genus_ids
integer
Example: genus_ids=2,3

Comma-separated list of genus IDs. Includes plots that have planted any variety of any of these genera

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

variety_ids
Array of integers

Comma-separated list of variety variety IDs. Include plots that have planted any of these varieties.

tag_id
integer >= 1

Filter by crop tag ID. Include objects that have been tagged with this tag.

tag_ids
Array of integers
Example: tag_ids=2,3

Comma-separated list of crop tag IDs. Includes objects that have been tagged with any of these tags

crop_variety_id
integer >= 1
Deprecated
Example: crop_variety_id=1

Filter by the variety ID. Deprecated: use variety_id

growing_season
string
Example: growing_season=2020/21

Filter by growing season

created_by_id
integer >= 1
Example: created_by_id=1

Filter by the user ID who created these entities

slug
string
Deprecated

Search by the legacy "slug" identifier

search
string

Search for plot name

field_name
string

Return the plots associated with these fields.

is_active
boolean
Deprecated

If true then return the plots that are currently active i.e that have not been marked as harvested and closed. If false then only return the plots that have been harvested and closed i.e are not currently considered "active". If not specified then return plots disregarding the active state.

state
string
Enum: "all" "open" "closed"

If open then return the plots that are currently active i.e that have not been marked as closed (currently "active"). If closed then only return the plots that have been closed i.e that have been marked as closed (currently "inactive"). If all specified then return plots disregarding the active state. If not specified then returns open (currently "active") plots only.

status
string (PlotStatusValues)
Enum: "Ready to sample" "Awaiting results" "Resample" "Results received" "Resample results received" "Ready for harvest" "NOC" "Crop unsuitable" "Scheduled for harvest" "Harvested"

Filter by current plot status

sowing_from
string <date>
Example: sowing_from=2020-01-01

Filter results by sowing operation after a given date

sowing_to
string <date>
Example: sowing_to=2020-01-02

Filter results by sowing operation up to a given date

harvest_from
string <date>
Example: harvest_from=2020-01-01

Filter results by harvest operation after a given date

harvest_to
string <date>
Example: harvest_to=2020-01-02

Filter results by harvest operation up to a given date

off_platform
string
Enum: "only" "exclude"

If only then only returns "off-platform" plots· If exclude then exclude "off-platform" plots. If not specified that all plots are returned.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Create a new plot

Create a new plot within a field. A user with TEAM_ADMIN will be able to create a new plot for their farm. An Enterprise user with SITE_ADMIN permission will be able to create a plot for any fields owned by any of their client teams. A Kisanhub staff user may create a plot for any field.

Request Body schema: application/json
field_id
required
integer (FieldId) >= 1

Field ID.

object (Boundary)

Bounding polygon

crop_id
required
integer (CropId) >= 1

Crop ("genus") ID. Note that value is taken from the most recent sowing operation.

name
string (PlotName)

Name. If this field is left blank while creating the plot, a name will be auto-generated in the format YYYY-0, where YYYY is current year.

slug
string
Deprecated

Legacy identifier

notes
string

Notes

variety_id
integer >= 1

Variety ID - see /api/variety for more detail

soil_type_id
integer >= 1

Soil type ID. If not specified then we assume the soil type of the field.

open
boolean

A plot is open when it is actively growing produce i.e it has not undergone a final harvest or been abandoned.

planned_planting_date
string <date-time>

Planned planting date. Editing this property will result in the creation of a new sowing operation

actual_planting_date
string <date-time>

Actual planting date. Editing this property will result in the creation of a new sowing operation

planting_area
number

The planting (i.e sown) area in ha. If not specified then we assume the working area is the full plot area as specified in bounds.area. Note that this is tied to the sown_area in the most recent sowing operation.

planned_harvest_date
string <date-time>

Planned harvest date. Editing this property will result in the creation of a new harvest operation, along with any planned_yield

planned_yield
number or null

Planned harvest yield, in t/ha. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

planned_quantity
number or null

Planned harvest quantity, in tonnes. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

actual_harvest_date
string <date-time>

Actual date of harvest. Editing this property will result in the creation of a new harvest operation, along with any actual_yield

actual_yield
number

Actual harvest yield, in t/ha. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

actual_quantity
number

Actual harvest quantity, in tonnes. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

object
Deprecated

Deprecated planting information. Please use planned_planting_date and actual_planting_date in preference: if either of those properties are specified then this section will be ignored.

object
Deprecated

Deprecated harvest information. Please use planned_harvest_date, planned_yield, actual_harvest_date and actual_yield in preference. If either of those properties are specified then this section will be ignored.

registration_code
string

A code that uniquely and globally identifies this plot

governmental_code
string

A country-specific code that uniquely identifies this plot

agronomist_ids
Array of integers

user ids list who are agronomists

owner_id
integer >= 1

The designated plot owner

growing_season
Array of strings

The growing season for this plot, like 2019/20. A plot can have more than one season

is_seed
boolean
Default: false

Is what's growing here for seed?

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

tag_ids
Array of integers

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "centroid": [
    ],
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "farm_id": 2,
  • "team_id": 1,
  • "organisation_id": 1,
  • "access": "read-edit",
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "tag_ids": [
    ],
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get plot by ID

get the plot identified by the ID in the URL

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "farm_id": 2,
  • "team_id": 1,
  • "organisation_id": 1,
  • "access": "read-edit",
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "tag_ids": [
    ],
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": "Ready to sample"
}

Delete plot

Delete the plot. Note that only plots which satisfy the following constraints may be deleted:

  • The plot has either no operations at all, or a single planned sowing operation only
  • The plot has no observations associated with it
path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Update plot

Update an existing plot within a field. A user with TEAM_ADMIN will be able to update any plot for their farm. A user with SITE_ADMIN permission will be able to update a plot for any fields owned by any of their client teams. A Kisanhub staff user may update any plot.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
field_id
required
integer (FieldId) >= 1

Field ID.

object (Boundary)

Bounding polygon

crop_id
required
integer (CropId) >= 1

Crop ("genus") ID. Note that value is taken from the most recent sowing operation.

name
string (PlotName)

Name. If this field is left blank while creating the plot, a name will be auto-generated in the format YYYY-0, where YYYY is current year.

slug
string
Deprecated

Legacy identifier

notes
string

Notes

variety_id
integer >= 1

Variety ID - see /api/variety for more detail

soil_type_id
integer >= 1

Soil type ID. If not specified then we assume the soil type of the field.

open
boolean

A plot is open when it is actively growing produce i.e it has not undergone a final harvest or been abandoned.

planned_planting_date
string <date-time>

Planned planting date. Editing this property will result in the creation of a new sowing operation

actual_planting_date
string <date-time>

Actual planting date. Editing this property will result in the creation of a new sowing operation

planting_area
number

The planting (i.e sown) area in ha. If not specified then we assume the working area is the full plot area as specified in bounds.area. Note that this is tied to the sown_area in the most recent sowing operation.

planned_harvest_date
string <date-time>

Planned harvest date. Editing this property will result in the creation of a new harvest operation, along with any planned_yield

planned_yield
number or null

Planned harvest yield, in t/ha. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

planned_quantity
number or null

Planned harvest quantity, in tonnes. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

actual_harvest_date
string <date-time>

Actual date of harvest. Editing this property will result in the creation of a new harvest operation, along with any actual_yield

actual_yield
number

Actual harvest yield, in t/ha. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

actual_quantity
number

Actual harvest quantity, in tonnes. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

object
Deprecated

Deprecated planting information. Please use planned_planting_date and actual_planting_date in preference: if either of those properties are specified then this section will be ignored.

object
Deprecated

Deprecated harvest information. Please use planned_harvest_date, planned_yield, actual_harvest_date and actual_yield in preference. If either of those properties are specified then this section will be ignored.

registration_code
string

A code that uniquely and globally identifies this plot

governmental_code
string

A country-specific code that uniquely identifies this plot

agronomist_ids
Array of integers

user ids list who are agronomists

owner_id
integer >= 1

The designated plot owner

growing_season
Array of strings

The growing season for this plot, like 2019/20. A plot can have more than one season

is_seed
boolean
Default: false

Is what's growing here for seed?

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

tag_ids
Array of integers

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "centroid": [
    ],
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "farm_id": 2,
  • "team_id": 1,
  • "organisation_id": 1,
  • "access": "read-edit",
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "tag_ids": [
    ],
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Partial plot update

Partially update an existing plot within a field. Only those properties supplied will be updated.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Request Body schema: application/json
name
string

Name. If this field is left blank while creating the plot, a name will be auto-generated in the format YYYY-0, where YYYY is current year.

field_id
integer (FieldId) >= 1

Field ID.

object (Boundary)

Bounding polygon

crop_id
integer (CropId) >= 1

Crop ("genus") ID. Note that value is taken from the most recent sowing operation.

slug
string
Deprecated

Legacy identifier

notes
string

Notes

variety_id
integer >= 1

Variety ID - see /api/variety for more detail

soil_type_id
integer >= 1

Soil type ID. If not specified then we assume the soil type of the field.

open
boolean

A plot is open when it is actively growing produce i.e it has not undergone a final harvest or been abandoned.

planned_planting_date
string <date-time>

Planned planting date. Editing this property will result in the creation of a new sowing operation

actual_planting_date
string <date-time>

Actual planting date. Editing this property will result in the creation of a new sowing operation

planting_area
number

The planting (i.e sown) area in ha. If not specified then we assume the working area is the full plot area as specified in bounds.area. Note that this is tied to the sown_area in the most recent sowing operation.

planned_harvest_date
string <date-time>

Planned harvest date. Editing this property will result in the creation of a new harvest operation, along with any planned_yield

planned_yield
number or null

Planned harvest yield, in t/ha. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

planned_quantity
number or null

Planned harvest quantity, in tonnes. If a planned_harvest_date is also supplied then this will result in the creation of a new planned harvest operation, if one does not exist, or the update of an existing planned harvest operation.

actual_harvest_date
string <date-time>

Actual date of harvest. Editing this property will result in the creation of a new harvest operation, along with any actual_yield

actual_yield
number

Actual harvest yield, in t/ha. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

actual_quantity
number

Actual harvest quantity, in tonnes. Editing this property will result in the creation of a new harvest operation, along with any actual_harvest_date

object
Deprecated

Deprecated planting information. Please use planned_planting_date and actual_planting_date in preference: if either of those properties are specified then this section will be ignored.

object
Deprecated

Deprecated harvest information. Please use planned_harvest_date, planned_yield, actual_harvest_date and actual_yield in preference. If either of those properties are specified then this section will be ignored.

registration_code
string

A code that uniquely and globally identifies this plot

governmental_code
string

A country-specific code that uniquely identifies this plot

agronomist_ids
Array of integers

user ids list who are agronomists

owner_id
integer >= 1

The designated plot owner

created_at
string <date-time>

Date this plot was created

growing_season
Array of strings

The growing season for this plot, like 2019/20. A plot can have more than one season

is_seed
boolean
Default: false

Is what's growing here for seed?

centroid
Array of numbers <float> (Point) = 2 items [ items <float > ]

Point location as a [lng, lat] pair

tag_ids
Array of integers

List of associated crop tags ids

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "centroid": [
    ],
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "field_id": 1,
  • "boundary": {
    },
  • "crop_id": 1,
  • "farm_id": 2,
  • "team_id": 1,
  • "organisation_id": 1,
  • "access": "read-edit",
  • "name": "string",
  • "slug": "string",
  • "notes": "string",
  • "variety_id": 1,
  • "soil_type_id": 1,
  • "open": true,
  • "planned_planting_date": "2020-04-01T11:00:00Z",
  • "actual_planting_date": "2020-04-07T10:00:00Z",
  • "planting_area": 0,
  • "planned_harvest_date": "2020-07-01T09:00:00Z",
  • "planned_yield": 10,
  • "planned_quantity": 10,
  • "actual_harvest_date": "2020-07-02T09:00:00Z",
  • "actual_yield": 12.5,
  • "actual_quantity": 12.5,
  • "planting": {
    },
  • "harvest": {
    },
  • "registration_code": "string",
  • "governmental_code": "string",
  • "agronomist_ids": [
    ],
  • "owner_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "growing_season": [
    ],
  • "is_seed": false,
  • "weather_station_slug": "string",
  • "location_slug": "string",
  • "centroid": [
    ],
  • "tag_ids": [
    ],
  • "created_by_id": 1,
  • "created_by_name": "Billy bob",
  • "updated_by_id": 1,
  • "updated_by_name": "Billy bob",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get plot permission

Returns the permission level for this plot. A user has read access to a plot if any of the following conditions are met:

  • It is in their farm
  • The user has SITE_ADMIN access to the same Site as the Farm
  • The user has current read or read/write access via a team share to the Plot
  • The user is KisanHub staff

A user has read-only access only if the user has only read-only access to the associated plot via a team share.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

Responses

Response samples

Content type
application/json
{
  • "access": "read-edit",
  • "noDeleteReason": "string"
}

Update plot status

Update the status for a specific plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Request Body schema: application/json
status
string (PlotStatusValues)
Enum: "Ready to sample" "Awaiting results" "Resample" "Results received" "Resample results received" "Ready for harvest" "NOC" "Crop unsuitable" "Scheduled for harvest" "Harvested"

Plot status string

Responses

Request samples

Content type
application/json
{
  • "status": "Ready to sample"
}

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

List plot team shares

List of teams a plot has been shared with, and with what permissions

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Share a plot with a team

Share a plot with a team

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Request Body schema: application/json
allow_edit
boolean

The team has edit permissions on the plot

team_id
integer

Team ID

team_name
string

Team name

Responses

Request samples

Content type
application/json
{
  • "allow_edit": true,
  • "team_id": 1,
  • "team_name": "Team 2"
}

Response samples

Content type
application/json
{
  • "allow_edit": true,
  • "team_id": 1,
  • "team_name": "Team 2"
}

Remove team share

Remove a share from a team for a plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Request Body schema: application/json
team_id
integer

Responses

Request samples

Content type
application/json
{
  • "team_id": 1
}

List crop tags for a plot

List of crop tags on a plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

Add a crop tag to a plot

Add a tag to a plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Request Body schema: application/json
tag_id
integer >= 1

ID of the crop tag added to this plot

Responses

Request samples

Content type
application/json
{
  • "tag_id": 1
}

Response samples

Content type
application/json
{
  • "tag_id": "string",
  • "plot_id": 1
}

Remove a crop tag from a plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

tag_id
required
integer >= 1

Crop tag ID.

Responses

List crop tags assignable to this plot

List of crop tags assignable to this plot

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

Plot ID

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

List deleted plots

List plot ids which have been deleted since a given date

query Parameters
from_date
required
string <date-time>

Include deleted plots from this date

Responses

Response samples

Content type
application/json
[
  • 0
]

List GeoJSON plots

Plot summaries in GeoJSON format

query Parameters
team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

season
string
Deprecated
Example: season=2019/20

Growing season

bounds
Array of integers[ items = 4 characters ]
Example: bounds=-0.6287,53.8621,-0.5636,53.8830

Only return features that are contained within the bounding box (including intersects)

Format is xMin,yMin,xMax,yMax (i.e lng,lat NW / SE)

state
string
Enum: "all" "open" "closed"

If open then return the plots that are currently active i.e that have not been marked as closed (currently "active"). If closed then only return the plots that have been closed i.e that have been marked as closed (currently "inactive"). If all specified then return plots disregarding the active state. If not specified then returns open (currently "active") plots only.

Responses

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

List varieties planted

Returns the set of varieties planted, grouped by genus

query Parameters
farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

growing_season
string
Example: growing_season=2020/21

Filter by growing season

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List possible plot status

Return the list of all possible plot status values

Responses

Response samples

Content type
application/json
[
  • "Ready to sample"
]

Get farmed regions

Returns a list of farm regions in which we have active plots.

query Parameters
from_date
string <date>
Example: from_date=2020-01-02T10:00:00Z

From date

to_date
string <date>
Example: to_date=2020-01-23T15:00:00Z

To date

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get plot team groups Deprecated

Returns a list of team-group associated with active plots teams.

query Parameters
from_date
string <date>
Example: from_date=2020-01-02T10:00:00Z

From date

to_date
string <date>
Example: to_date=2020-01-23T15:00:00Z

To date

Responses

Response samples

Content type
application/json
[
  • "string"
]

List plot genera

Returns the set of crops (i.e genus) and varieties planted

query Parameters
from_date
string <date>

Exclude plots harvested before this date

to_date
string <date>

Exclude plots planted after this date

region_name
string

Name of the region

team_group
string

Label of Team group

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Plot inventory report list

Return a human-readable report of the entire plot inventory.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

team_ids
integer
Example: team_ids=1,2,3

Comma-separated list of team IDs.

organisation_id
integer >= 1
Example: organisation_id=1

Filter by the organisation ID

organisation_ids
integer
Example: organisation_ids=1,2,3

Comma-separated list of organisation IDs.

group_id
integer >= 1
Example: group_id=43

Filter by the organisation group ID

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

variety_ids
Array of integers

Comma-separated list of variety variety IDs. Include plots that have planted any of these varieties.

tag_id
integer >= 1

Filter by crop tag ID. Include objects that have been tagged with this tag.

tag_ids
Array of integers
Example: tag_ids=2,3

Comma-separated list of crop tag IDs. Includes objects that have been tagged with any of these tags

crop_variety_id
integer >= 1
Deprecated
Example: crop_variety_id=1

Filter by the variety ID. Deprecated: use variety_id

growing_season
string
Example: growing_season=2020/21

Filter by growing season

slug
string
Deprecated

Search by the legacy "slug" identifier

search
string

Search for plot name

field_name
string

Return the plots associated with these fields.

is_active
boolean
Deprecated

If true then return the plots that are currently active i.e that have not been marked as harvested and closed. If false then only return the plots that have been harvested and closed i.e are not currently considered "active". If not specified then return plots disregarding the active state.

status
string (PlotStatusValues)
Enum: "Ready to sample" "Awaiting results" "Resample" "Results received" "Resample results received" "Ready for harvest" "NOC" "Crop unsuitable" "Scheduled for harvest" "Harvested"

Filter by current plot status

state
string
Enum: "all" "open" "closed"

If open then return the plots that are currently active i.e that have not been marked as closed (currently "active"). If closed then only return the plots that have been closed i.e that have been marked as closed (currently "inactive"). If all specified then return plots disregarding the active state. If not specified then returns open (currently "active") plots only.

sowing_from
string <date>
Example: sowing_from=2020-01-01

Filter results by sowing operation after a given date

sowing_to
string <date>
Example: sowing_to=2020-01-02

Filter results by sowing operation up to a given date

harvest_from
string <date>
Example: harvest_from=2020-01-01

Filter results by harvest operation after a given date

harvest_to
string <date>
Example: harvest_to=2020-01-02

Filter results by harvest operation up to a given date

off_platform
string
Enum: "only" "exclude"

If only then only returns "off-platform" plots· If exclude then exclude "off-platform" plots. If not specified that all plots are returned.

format
string
Default: "json"
Enum: "csv" "json"
Example: format=csv

Change the output format. Defaults to JSON

Responses

Response samples

Content type
{
  • "total": 0,
  • "crop_type_count": 0,
  • "results": [
    ]
}

Get plot inventory statistics

Return aggregated totals for various metrics for the matching set of plots

query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Page size

farm_id
integer >= 1
Example: farm_id=2

Filter by the farm ID

field_id
integer >= 1
Example: field_id=3

Filter by the field ID

team_id
integer >= 1
Example: team_id=42

Filter by the team ID

genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

variety_id
integer >= 1
Example: variety_id=1

Filter by the variety ID

crop_variety_id
integer >= 1
Deprecated
Example: crop_variety_id=1

Filter by the variety ID. Deprecated: use variety_id

growing_season
string
Example: growing_season=2020/21

Filter by growing season

slug
string
Deprecated

Search by the legacy "slug" identifier

search
string

Search for plot name

field_name
string

Return the plots associated with these fields.

is_active
boolean
Deprecated

If true then return the plots that are currently active i.e that have not been marked as harvested and closed. If false then only return the plots that have been harvested and closed i.e are not currently considered "active". If not specified then return plots disregarding the active state.

status
string (PlotStatusValues)
Enum: "Ready to sample" "Awaiting results" "Resample" "Results received" "Resample results received" "Ready for harvest" "NOC" "Crop unsuitable" "Scheduled for harvest" "Harvested"

Filter by current plot status

state
string
Enum: "all" "open" "closed"

If open then return the plots that are currently active i.e that have not been marked as closed (currently "active"). If closed then only return the plots that have been closed i.e that have been marked as closed (currently "inactive"). If all specified then return plots disregarding the active state. If not specified then returns open (currently "active") plots only.

sowing_from
string <date>
Example: sowing_from=2020-01-01

Filter results by sowing operation after a given date

sowing_to
string <date>
Example: sowing_to=2020-01-02

Filter results by sowing operation up to a given date

harvest_from
string <date>
Example: harvest_from=2020-01-01

Filter results by harvest operation after a given date

harvest_to
string <date>
Example: harvest_to=2020-01-02

Filter results by harvest operation up to a given date

off_platform
string
Enum: "only" "exclude"

If only then only returns "off-platform" plots· If exclude then exclude "off-platform" plots. If not specified that all plots are returned.

Responses

Response samples

Content type
application/json
{
  • "farms": 4,
  • "plots": 23,
  • "cropped_area": 11.52,
  • "planted_plots": 22,
  • "harvested_plots": 20,
  • "expected_production": 55.5
}

Genus

Crop genus

List genera

Returns a list of available genera (often called "crop"). Names are translated according to the Accept-Language header, defaulting to English.

query Parameters
crop_name
string
Example: crop_name=Potato

Filter by the genus name

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get crop genus

Returns a single genus (often called "crop"). Names are translated according to the Accept-Language header, defaulting to English.

path Parameters
id
required
integer (PrimaryKey) >= 1
Example: 1

ID

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "colour_code": "string",
  • "is_perennial": true
}

Get growth stages for genera

Returns lists of primary and secondary growth stages associated with each genus

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get growth stage for genus

Returns a list of primary and secondary growth stages associated with a given genus

path Parameters
genus_id
required
integer (PrimaryKey) >= 1
Example: 1

ID

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "primary_growth_stages": [
    ]
}

Variety

Crop variety

List varieties

Return an unpaginated list of available crop varieties. Names are translated according to the Accept-Language header, defaulting to English.

query Parameters
genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create variety

Create a new crop variety. Uniqness is enforced for the name (for the given genus). Only available to users with VARIETY_ADMIN permission or KisanHub staff.

Request Body schema: application/json
name
string

Name

crop_id
integer >= 1

Genus ID - see /api/genus for more detail

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "crop_id": 1
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string",
  • "crop_id": 1
}

List varieties - paginated

Return an paginated list of available crop varieties. Names are translated according to the Accept-Language header, defaulting to English.

query Parameters
genus_id
integer >= 1
Example: genus_id=1

Filter by the genus ID

string or string (DateOrDateTime)
Example: updated_since=2020-01-02T10:00:00Z

Return items created or updated since the specified data/time (inclusive). Date times are always in UTC and are specified in RFC3339 format. Can also be specified as simple dates e.g 2020-01-01, in which case midnight is assumed for the time component.

header Parameters
Accept-Language
string (Language)
Default: en
Enum: "en" "hi" "mr" "es"
Example: en

Return localised data for the given language

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Variety report

List varieties with their associated genus

Responses

Response samples

Content type
application/json
[
  • {
    }
]