awherepy.fields

A module to access and work with aWhere fields.

awherepy.fields.create_field(key, secret, field_info)[source]

Creates a field associated with an aWhere application.

API reference: https://docs.awhere.com/knowledge-base-docs/field-plantings/

Parameters

  • key (str) – API key for a valid aWhere API application.

  • secret (str) – API secret for a valid aWhere API application.

  • field_info (dict) –

    Dictionary containing the information required to create an aWhere field. Can contain the following keys:

    field_id: str, required

    ID for the field. This ID is used to reference the field in all applicable aWhere APIs. Can contain only alphanumeric characters, underscores, and dashes. Maximum 50 characters.

    center_latitude: int or float, required

    Latitiude (in decimal degrees) of the field center point.

    center_longitude: int or float, required

    Longitude (in decimal degrees) of the field center point.

    farm_id: str, required

    Name of the farm. Not referenced by any other aWhere APIs. Can contain only alphanumeric characters, underscores, and dashes. Maximum 50 characters.

    field_name: str, optional

    Name of the field. Not referenced by any other aWhere APIs. Can contain only alphanumeric characters, underscores, and dashes. Maximum 255 characters.

    acres: int or float, optional

    Size of the field in acres.

Returns

field – Geodataframe containing the newly-created aWhere field.

Return type

geopandas geodataframe

Example

>>> # Imports
>>> import os
>>> import awherepy as aw
>>> import awherepy.fields as awf
>>> # Get aWhere API key and secret
>>> awhere_api_key = os.environ.get('AWHERE_API_KEY')
>>> awhere_api_secret = os.environ.get('AWHERE_API_SECRET')
>>> # Define field information for Manchester, Vermont
>>> manchester_field_info = {
...     'field_id': 'VT-Manchester',
...     'field_name': 'Manchester-Field',
...     'farm_id': 'Manchester-Farm',
...     'center_latitude': 43.1636875,
...     'center_longitude': -73.0723269,
...     'acres': 1
... }
>>> Create field
>>> field = awf.create_field(
...    api_key, api_secret, field_info=manchester_field_info
... )
Attempting to create field...
Created field: VT-Manchester
>>> # Check geodataframe index (field id)
>>> print(field.index[0])
VT-Manchester
>>> # Display field
>>> field
awherepy.fields.delete_field(key, secret, field_id)[source]

Deletes a speficied aWhere field.

API reference: https://docs.awhere.com/knowledge-base-docs/field-plantings/

Parameters

  • key (str) – API key for a valid aWhere API application.

  • secret (str) – API secret for a valid aWhere API application.

  • field_id (str) – Field ID for an existing aWhere field. This identifies the field that will be deleted from the aWhere application.

Returns

message – Output message indicating success or failure for the field deletion.

Return type

str

Example

>>> # Imports
>>> import os
>>> import awherepy as aw
>>> import awherepy.fields as awf
>>> # Get aWhere API key and secret
>>> awhere_api_key = os.environ.get('AWHERE_API_KEY')
>>> awhere_api_secret = os.environ.get('AWHERE_API_SECRET')
>>> # Delete field for Manchester, Vermont
>>> awf.delete_field(
...     awhere_api_key, awhere_api_secret, field_id='VT-Manchester'
... )
Attempting to delete field...
Deleted field: VT-Manchester
awherepy.fields.get_fields(key, secret, kwargs=None)[source]

Returns fields (all or individual) associated with an aWhere application.

API reference: https://docs.awhere.com/knowledge-base-docs/field-plantings/

Parameters

  • key (str) – API key for a valid aWhere API application.

  • secret (str) – API secret for a valid aWhere API application.

  • kwargs (dict, optional) –

    Keyword arguments for different query parameters. Running the function without kwargs will use the default values. Arguments include:

    field_id: str

    Field ID for a valid aWhere field associated with the input API key/secret. Causes the function to return a single field if the value is not None. If value is None, all fields associated with the API key/secret will be returned. Default value is None.

    limit: int

    Number of results in the API response per page. Used with offset kwarg to sort through pages of results (cases where the number of results exceeds the limit per page). Applicable when the number of results exceeds 1. Maximum value is 10. Default value is 10.

    offset: int

    Number of results in the API response to skip. Used with limit kwarg to sorts through pages of results (cases where the number of results exceeds the limit per page). Applicable when the number of results exceeds 1. Default value is 0 (start with first result).

Returns

fields_gdf – Geodataframe containing all fields or an individual field.

Return type

geopandas geodataframe

Example

>>> # Imports
>>> import os
>>> import awherepy as aw
>>> import awherepy.fields as awf
>>> # Get aWhere API key and secret
>>> awhere_api_key = os.environ.get('AWHERE_API_KEY')
>>> awhere_api_secret = os.environ.get('AWHERE_API_SECRET')
>>> # Get all fields associated with key/secret
>>> all_fields = awf.get_fields(awhere_api_key, awhere_api_secret)
>>> # Check number of entries in field
>>> len(all_fields)
3
>>> # Define kwargs for single field
>>> manchester_vt_kwargs = {'field_id': 'Manchester-VT'}
>>> # Get a single field
>>> manchester_vt_field = awf.get_fields(
...     awhere_api_key, awhere_api_secret, kwargs=manchester_vt_kwargs)
>>> # Check number of entries
>>> len(manchester_vt_field)
1
awherepy.fields.update_field(key, secret, field_info)[source]

Update the field name and/or farm id for a specified field.

API reference: https://docs.awhere.com/knowledge-base-docs/field-plantings/

Parameters

  • key (str) – API key for a valid aWhere API application.

  • secret (str) – API secret for a valid aWhere API application.

  • field_info (dict) –

    Dictionary containing information required to update the field. Must provide an update to field_name or farm_id (cannot make empty update). Can contain the following keys:

    field_id: str, required

    Field ID for an existing aWhere field. This identifies the field that will be updated.

    field_name: str, required if farm_id not specified

    Updated field name.

    farm_id: str, required if field_name is not specified

    Updated farm ID.

Returns

field – Geodataframe containing the updated aWhere field.

Return type

geopandas geodataframe

Example

>>> # Imports
>>> import os
>>> import awherepy as aw
>>> import awherepy.fields as awf
>>> # Get aWhere API key and secret
>>> awhere_api_key = os.environ.get('AWHERE_API_KEY')
>>> awhere_api_secret = os.environ.get('AWHERE_API_SECRET')
>>> # Define update parameters for Manchester, Vermont
>>> manchester_update_info = {
...     'field_id': 'VT-Manchester',
...     'field_name': 'Manchester-Field-Update',
...     'farm_id': 'Manchester-Farm-Update'
... }
>>> # Update the field
>>> field_updated = awf.update_field(
...     api_key, api_secret,
...     field_info=manchester_update_info
... )
Attempting to update field...
Updated field: VT-Manchester
>>> # Display updated field
>>> field_updated