---
updatedAt: 2025-08-25T12:23:11.000Z
agentTools:
projectIndex: https://developer.varda.ag/llms.txt
---
# Look up FieldIDs for a given Point, Polygon or MultiPolygon.
This endpoint returns the fields intersecting input geometry, along with active BoundaryIDs.
It supports two types of inputs:
1. Point
2. Polygon (or MultiPolygon)
For #2 the ratio of overlap and the IoU score are added to the output.
Spatial search area limit is 25 km2.
GeoJSON input can be provided directly or encapsulated within the geometry of a GeoJSON Feature. Input must comply with [**ISO 19125**](https://www.iso.org/standard/40114.html).
# OpenAPI definition
```json
{
"openapi": "3.0.3",
"info": {
"title": "Field ID API",
"x-visibility": "public",
"description": "API endpoints to integrate with the Global FieldID system.\nProtected by OAuth2.0 client credentials",
"contact": {
"email": "support@varda.ag"
},
"version": "v1"
},
"servers": [
{
"url": "https://api.varda.ag/fid/v1",
"description": "Global FieldID API"
}
],
"security": [
{
"Varda-JWT": []
}
],
"tags": [
{
"name": "Fields",
"description": ""
}
],
"paths": {
"/field-searches": {
"post": {
"tags": [
"Fields"
],
"summary": "Look up FieldIDs for a given Point, Polygon or MultiPolygon.",
"description": "This endpoint returns the fields intersecting input geometry, along with active BoundaryIDs.\n\nIt supports two types of inputs:\n\n1. Point\n\n2. Polygon (or MultiPolygon)\n\nFor #2 the ratio of overlap and the IoU score are added to the output.
Spatial search area limit is 25 km2.\n\nGeoJSON input can be provided directly or encapsulated within the geometry of a GeoJSON Feature. Input must comply with [**ISO 19125**](https://www.iso.org/standard/40114.html).",
"operationId": "field_searches",
"parameters": [
{
"$ref": "#/components/parameters/AcceptLanguageHeader"
},
{
"in": "query",
"name": "offset",
"description": "Number of records to skip.",
"required": false,
"schema": {
"type": "integer",
"format": "",
"default": 0,
"minimum": 0
}
},
{
"in": "query",
"name": "limit",
"description": "Maximum number of records to return.",
"required": false,
"schema": {
"type": "integer",
"format": "0",
"default": 50,
"minimum": 1,
"maximum": 100
}
}
],
"requestBody": {
"content": {
"application/geo+json": {
"schema": {
"$ref": "#/components/schemas/FieldSearchRequest"
},
"examples": {
"GeoJSONPoint": {
"$ref": "#/components/examples/GeoJSONPoint"
},
"GeoJSONPointFeature": {
"$ref": "#/components/examples/GeoJSONPointFeature"
},
"GeoJSONPolygon": {
"$ref": "#/components/examples/GeoJSONPolygon"
},
"GeoJSONPolygonFeature": {
"$ref": "#/components/examples/GeoJSONPolygonFeature"
},
"GeoJSONMultiPolygon": {
"$ref": "#/components/examples/GeoJSONMultiPolygon"
},
"GeoJSONMultiPolygonFeature": {
"$ref": "#/components/examples/GeoJSONMultiPolygonFeature"
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/FieldSearchResult"
},
"400": {
"description": "Bad Request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
},
"401": {
"description": "Authorization information is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
},
"403": {
"description": "Access Denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
},
"422": {
"description": "Missing or Invalid Request Body.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"Varda-JWT": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "A JWT access token is required. See [Requesting Access Tokens](https://developer.varda.ag/docs/request-access-token)."
}
},
"parameters": {
"AcceptLanguageHeader": {
"name": "Accept-Language",
"in": "header",
"description": "Language and locale to return the response in",
"required": false,
"schema": {
"type": "string"
},
"examples": {
"en": {
"summary": "English",
"value": "en"
},
"pt": {
"summary": "Portuguese",
"value": "pt"
}
}
}
},
"responses": {
"FieldSearchResult": {
"description": "Contains entries sorted by relevance",
"content": {
"application/json": {
"schema": {
"properties": {
"entries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldSearchResultEntry"
}
}
},
"example": {
"entries": [
{
"field_id": "123A.BCDE",
"boundary_id": "123e4567-e89b-72d3-8456-426614174000",
"iou_score": 0.25,
"input_based_intersection": 1,
"output_based_intersection": 0.25
}
]
}
}
}
}
}
},
"schemas": {
"FieldSearchRequest": {
"description": "Subset of GeoJSON standard used as a search request",
"allOf": [
{
"required": [
"type"
]
},
{
"oneOf": [
{
"$ref": "#/components/schemas/Point"
},
{
"$ref": "#/components/schemas/Polygon"
},
{
"$ref": "#/components/schemas/MultiPolygon"
},
{
"$ref": "#/components/schemas/Feature"
}
],
"discriminator": {
"propertyName": "type"
}
}
]
},
"FieldSearchResultEntry": {
"properties": {
"field_id": {
"$ref": "#/components/schemas/FieldId"
},
"boundary_id": {
"$ref": "#/components/schemas/BoundaryId"
},
"iou_score": {
"description": "Intersection over union. Values are in range between `0.0` and `1.0`.\nFor search by a single point, always `undefined`",
"type": "number"
},
"input_based_intersection": {
"description": "Input-relative ratio of overlap of the input boundary with an output field boundary. Values are in range between `0.0` and `1.0`.\nFor search by a single point, always `undefined`",
"type": "number"
},
"output_based_intersection": {
"description": "Output-relative ratio of overlap of the input boundary with an output field boundary. Values are in range between `0.0` and `1.0`.\nFor search by a single point, always `undefined`",
"type": "number"
}
}
},
"FieldId": {
"type": "string",
"example": "123A.BCDE",
"pattern": "^[0-9A-Z]{3,4}\\.[0-9A-Z]{3,4}$",
"maxLength": 9
},
"BoundaryId": {
"type": "string",
"format": "uuid",
"minLength": 36,
"maxLength": 36,
"example": "123e4567-e89b-72d3-8456-426614174000"
},
"APIError": {
"type": "object",
"properties": {
"error": {
"required": [
"title",
"status",
"detail"
],
"type": "object",
"properties": {
"title": {
"type": "string",
"example": "string"
},
"status": {
"type": "number",
"example": 0
},
"detail": {
"type": "string",
"example": "string"
}
}
}
}
},
"GeoJsonObject": {
"description": "GeoJSON object\nThe coordinate reference system for all GeoJSON coordinates is a geographic coordinate reference system, using the World Geodetic System 1984 (WGS 84) datum, with longitude and latitude units of decimal degrees. This is equivalent to the coordinate reference system identified by the Open Geospatial Consortium (OGC) URN An OPTIONAL third-position element SHALL be the height in meters above or below the WGS 84 reference ellipsoid. In the absence of elevation values, applications sensitive to height or depth SHOULD interpret positions as being at local ground or sea level.\n",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3"
},
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"Polygon",
"MultiPolygon",
"Point",
"MultiPoint",
"LineString",
"MultiLineString",
"GeometryCollection",
"Feature",
"FeatureCollection"
]
}
},
"required": [
"type"
],
"discriminator": {
"propertyName": "type"
}
},
"Geometry": {
"description": "Abstract type for all GeoJSON object except Feature and FeatureCollection\n",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3"
},
"allOf": [
{
"$ref": "#/components/schemas/GeoJsonObject"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"Point",
"MultiPoint",
"LineString",
"MultiLineString",
"Polygon",
"MultiPolygon",
"GeometryCollection"
]
}
},
"required": [
"type"
],
"discriminator": {
"propertyName": "type"
}
}
]
},
"GeometryElement": {
"description": "Abstract type for all GeoJSON 'Geometry' object the type of which is not 'GeometryCollection'\n",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3"
},
"allOf": [
{
"$ref": "#/components/schemas/Geometry"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"Point",
"MultiPoint",
"LineString",
"MultiLineString",
"Polygon",
"MultiPolygon"
]
}
},
"required": [
"type"
],
"discriminator": {
"propertyName": "type"
}
}
]
},
"Feature": {
"description": "GeoJSON 'Feature' object",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3.2"
},
"allOf": [
{
"$ref": "#/components/schemas/GeoJsonObject"
},
{
"type": "object",
"required": [
"geometry",
"properties"
],
"properties": {
"geometry": {
"allOf": [
{
"nullable": true
},
{
"$ref": "#/components/schemas/Geometry"
}
]
},
"properties": {
"type": "object",
"nullable": true
},
"id": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
]
}
}
}
]
},
"FeatureCollection": {
"description": "GeoJSON FeatureCollection object",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3.3"
},
"allOf": [
{
"$ref": "#/components/schemas/GeoJsonObject"
},
{
"type": "object",
"required": [
"features"
],
"properties": {
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Feature"
}
}
}
}
]
},
"Position": {
"description": "Note: Global FieldID API allows 3 values to be provided but 3rd one is not used.\nGeoJSon fundamental geometry construct.\nA position is an array of numbers. There MUST be two or more elements. The first two elements are longitude and latitude, or easting and northing, precisely in that order and using decimal numbers. Altitude or elevation MAY be included as an optional third element.\nImplementations SHOULD NOT extend positions beyond three elements because the semantics of extra elements are unspecified and ambiguous. Historically, some implementations have used a fourth element to carry a linear referencing measure (sometimes denoted as \"M\") or a numerical timestamp, but in most situations a parser will not be able to properly interpret these values. The interpretation and meaning of additional elements is beyond the scope of this specification, and additional elements MAY be ignored by parsers.\n",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3.1.1"
},
"type": "array",
"minItems": 2,
"maxItems": 3,
"items": {
"type": "number"
}
},
"LinearRing": {
"description": "A linear ring is a closed LineString with four or more positions.\nThe first and last positions are equivalent, and they MUST contain identical values; their representation SHOULD also be identical.\nA linear ring is the boundary of a surface or the boundary of a hole in a surface.\nA linear ring MUST follow the right-hand rule with respect to the area it bounds, i.e., exterior rings are counterclockwise, and holes are clockwise.\n",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3.1.6"
},
"type": "array",
"items": {
"$ref": "#/components/schemas/Position"
},
"minItems": 4
},
"Point": {
"description": "GeoJSON geometry",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3.1.2"
},
"allOf": [
{
"$ref": "#/components/schemas/GeometryElement"
},
{
"type": "object",
"required": [
"coordinates"
],
"properties": {
"coordinates": {
"$ref": "#/components/schemas/Position"
}
}
}
]
},
"Polygon": {
"description": "GeoJSON Polygon",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3.1.6"
},
"allOf": [
{
"$ref": "#/components/schemas/GeometryElement"
},
{
"type": "object",
"required": [
"coordinates"
],
"properties": {
"coordinates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LinearRing"
},
"minLength": 1
}
}
}
]
},
"MultiPolygon": {
"description": "GeoJSON MultiPolygon",
"externalDocs": {
"url": "https://tools.ietf.org/html/rfc7946#section-3.1.7"
},
"allOf": [
{
"$ref": "#/components/schemas/GeometryElement"
},
{
"type": "object",
"required": [
"coordinates"
],
"properties": {
"coordinates": {
"type": "array",
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LinearRing"
}
}
}
}
}
]
}
},
"examples": {
"GeoJSONPoint": {
"summary": "GeoJSON Point",
"value": {
"type": "Point",
"coordinates": [
1.443714,
47.089906
]
}
},
"GeoJSONPointFeature": {
"summary": "GeoJSON Point Feature",
"value": {
"type": "Feature",
"id": "myapp:1234",
"geometry": {
"type": "Point",
"coordinates": [
1.443714,
47.089906
]
},
"properties": {
"foo": "bar"
}
}
},
"GeoJSONPolygon": {
"summary": "GeoJSON Polygon",
"value": {
"type": "Polygon",
"coordinates": [
[
[
-46.557509425199356,
-15.31687689893279
],
[
-46.55216549195336,
-15.32154710598708
],
[
-46.54363701073163,
-15.313805444667594
],
[
-46.550027918654564,
-15.30932440654935
],
[
-46.557509425199356,
-15.31687689893279
]
]
]
}
},
"GeoJSONPolygonFeature": {
"summary": "GeoJSON Polygon Feature",
"value": {
"type": "Feature",
"id": "myapp:1234",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-46.557509425199356,
-15.31687689893279
],
[
-46.55216549195336,
-15.32154710598708
],
[
-46.54363701073163,
-15.313805444667594
],
[
-46.550027918654564,
-15.30932440654935
],
[
-46.557509425199356,
-15.31687689893279
]
]
]
},
"properties": {
"foo": "bar"
}
}
},
"GeoJSONMultiPolygon": {
"summary": "GeoJSON MultiPolygon",
"value": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-46.557509425199356,
-15.31687689893279
],
[
-46.55216549195336,
-15.32154710598708
],
[
-46.54363701073163,
-15.313805444667594
],
[
-46.550027918654564,
-15.30932440654935
],
[
-46.557509425199356,
-15.31687689893279
]
]
]
]
}
},
"GeoJSONMultiPolygonFeature": {
"summary": "GeoJSON MultiPolygon Feature",
"value": {
"type": "Feature",
"id": "myapp:1234",
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-46.557509425199356,
-15.31687689893279
],
[
-46.55216549195336,
-15.32154710598708
],
[
-46.54363701073163,
-15.313805444667594
],
[
-46.550027918654564,
-15.30932440654935
],
[
-46.557509425199356,
-15.31687689893279
]
]
]
]
},
"properties": {
"foo": "bar"
}
}
}
}
},
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true
}
}
```