> For the complete documentation index, see [llms.txt](https://docs.graniot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graniot.com/reference/api-reference/parcels.md).

# Parcels

Parcels represent individual agricultural plots or fields within a farm. Each parcel has a geometry (polygon), name, and can include custom metadata for filtering and organization.

## Parcel Metadata

The `metadata` field allows you to attach custom key-value data to any parcel. This is useful for storing information like supplier IDs, regions, crop types, or any other custom attributes your system needs.

### Creating Parcels with Metadata

When creating parcels via the API, include a `metadata` object:

```json
{
  "farm": {"id": 123},
  "parcels": [{
    "name": "Parcel A",
    "metadata": {
      "Supplier ID": "CPS-000111",
      "region": "North",
      "contract_year": "2024"
    },
    "geom": { ... }
  }]
}
```

### Updating Parcel Metadata

Use the PATCH endpoint to update metadata:

```
PATCH /api/parcels/{parcel_id}/
```

```json
{
  "id": 12345,
  "metadata": {
    "Supplier ID": "CPS-000111",
    "region": "North",
    "status": "active"
  }
}
```

### Viewing Metadata in Embedded Maps

Metadata is visible in the embedded map in two ways:

1. **Parcel tooltips**: Users can toggle which metadata fields appear when hovering over a parcel
2. **Parcel detail panel**: All metadata key-value pairs are displayed when opening a parcel's details

### Filtering by Metadata in Embedded Maps

You can filter the embedded map to show only parcels with specific metadata values using URL parameters:

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

See the [Embedded Maps](/embedded-maps.md) documentation for more filtering options.

***

{% openapi src="<https://app.graniot.com/api/doc/>" path="/api/parcels/" method="get" %}
<https://app.graniot.com/api/doc/>
{% endopenapi %}

{% openapi src="<https://app.graniot.com/api/doc/>" path="/api/parcels/" method="post" %}
<https://app.graniot.com/api/doc/>
{% endopenapi %}

{% openapi src="<https://app.graniot.com/api/doc/>" path="/api/parcels/{id}/" method="get" %}
<https://app.graniot.com/api/doc/>
{% endopenapi %}

{% openapi src="<https://app.graniot.com/api/doc/>" path="/api/parcels/{id}/" method="delete" %}
<https://app.graniot.com/api/doc/>
{% endopenapi %}

{% openapi src="<https://app.graniot.com/api/doc/>" path="/api/parcels/{id}/" method="patch" %}
<https://app.graniot.com/api/doc/>
{% endopenapi %}