Parcel Metadata

Parcel metadata allows you to attach custom key-value data to parcels. This is useful for storing business-specific information like supplier IDs, contract numbers, regions, or any other attributes your system needs.

What is Metadata?

The metadata field on a parcel is a flexible JSON object that accepts any key-value pairs:

{
  "metadata": {
    "Supplier ID": "CPS-000111",
    "region": "North",
    "contract_year": "2024",
    "crop_type": "Wheat",
    "certification": "Organic"
  }
}

Creating Parcels with Metadata

Include the metadata object when creating parcels:

curl

curl https://app.graniot.com/api/farms/ \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Graniot-Account: acc-52a220de-73e9-11ee-8cc3-0242ac130002' \
  -d '{
    "farm": {"name": "Customer Farm"},
    "parcels": [{
      "name": "Field A",
      "metadata": {
        "Supplier ID": "CPS-000111",
        "region": "North"
      },
      "geom": {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[-1.101, 38.139], [-1.100, 38.139], [-1.100, 38.138], [-1.101, 38.138], [-1.101, 38.139]]]
        }
      }
    }]
  }'

Python

Updating Metadata

Use the PATCH endpoint to update a parcel's metadata:

curl

curl https://app.graniot.com/api/parcels/12345/ \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Graniot-Account: acc-52a220de-73e9-11ee-8cc3-0242ac130002' \
  -d '{
    "id": 12345,
    "metadata": {
      "Supplier ID": "CPS-000111",
      "region": "North",
      "status": "verified"
    }
  }'

Python

When updating metadata, the entire metadata object is replaced. Make sure to include all key-value pairs you want to keep.

Viewing Metadata in Embedded Maps

Metadata is visible to users in the embedded map in two ways:

1. Parcel Tooltips

When hovering over a parcel, users can see metadata fields in the tooltip. Users can configure which metadata fields appear in tooltips through the map settings.

2. Parcel Detail Panel

When a user clicks on a parcel to open its details, all metadata key-value pairs are displayed in a dedicated section.

Filtering by Metadata in Embedded Maps

One of the most powerful features of metadata is the ability to filter the embedded map to show only parcels matching specific criteria.

URL Parameter Format

Add metadata[key]=value parameters to the embedded URL:

https://embed.graniot.com/?auth_id=YOUR_TOKEN&metadata[Supplier+ID]=CPS-000111

Encoding Spaces

When your metadata key contains spaces, encode them as + or %20:

Key	URL Parameter
Supplier ID	metadata[Supplier+ID]=value
Contract Year	metadata[Contract+Year]=value
region	metadata[region]=value

Examples

Filter by supplier:

https://embed.graniot.com/?auth_id=YOUR_TOKEN&metadata[Supplier+ID]=CPS-000111

Filter by region:

https://embed.graniot.com/?auth_id=YOUR_TOKEN&metadata[region]=North

Combine multiple filters:

https://embed.graniot.com/?auth_id=YOUR_TOKEN&metadata[Supplier+ID]=CPS-000111&metadata[region]=North

Filter with deforestation view:

https://embed.graniot.com/?auth_id=YOUR_TOKEN&metadata[Supplier+ID]=CPS-000111&resolution=DEFORESTATION

Use Cases

Supply Chain Traceability

Track product origins by storing supplier information:

{
  "metadata": {
    "Supplier ID": "SUP-12345",
    "Supplier Name": "Farm Co.",
    "Contract ID": "CNT-2024-001"
  }
}

Compliance Reporting

Store compliance-related data:

{
  "metadata": {
    "certification": "Organic",
    "audit_date": "2024-06-15",
    "compliance_status": "Verified"
  }
}

Regional Management

Organize parcels by geographic region:

{
  "metadata": {
    "region": "North",
    "district": "District A",
    "zone": "Zone 1"
  }
}

Best Practices

1. Use consistent keys - Establish naming conventions for metadata keys across your organization

2. Keep values simple - Use strings or simple values; avoid nested objects

3. Plan for filtering - Design metadata keys with filtering use cases in mind

4. Document your schema - Maintain documentation of what metadata keys your system uses