# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.graniot.com/reference/api-reference/parcels.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.