Climate FieldView Fields API

openapi: 3.2.0
info:
  title: Climate FieldView Platform Fields API
  description: '**Last Modified**: Mon Dec 8 16:27:39 UTC 2025


    All endpoints are only accessible via HTTPS. * All API endpoints are located at `https://platform.climate.com` (e.g. `https://platform.climate.com/v4/fields`). * The authorization token endpoint is located at

    `https://api.climate.com/api/oauth/token`. ## Troubleshooting


    `X-Http-Request-Id` response header will be returned on every call,

    successful or not. If you experience an issue with our api and need

    to contact technical support, please supply the value of the `X-Http-Request-Id`

    header along with an approximate time of when the request was made. ## Request Limits


    When you’re onboarded to Climate’s API platform, your `x-api-key` is assigned a custom usage plan. Usage plans are unique to each partner and have the following key attributes:


    1. Throttling information

    * burstLimit: Maximum rate limit over a period ranging from 1 second to a few seconds

    * rateLimit: A steady-state rate limit


    2. Quota information

    * Limit: The maximum number of requests that can be made in a given month


    When the request rate threshold is exceeded, a `429` response code is returned. Optionally, the `Retry-After` header may be returned:


    Following are examples of rate limit errors:


    1. Rate limit exceeded:


    HTTP/1.1 429


    Content-Type: application/json


    Content-Length: 32


    {"message":"Too Many Requests"}


    2. Quota exhausted:


    HTTP/1.1 429


    Content-Type: application/json


    Content-Length: 29


    {"message":"Limit Exceeded"}


    ## Pagination


    Pagination is performed via headers. Any request which returns a `"results"`

    array may be paginated. The following figure shows how query results are laid out with

    X-Limit=4 and no filter applied. * If there are no results, a response code of `304` will be returned. * If the response is the last set of results, a response code of `200` or

    `206` will be returned. * If there are more results, a response code of `206` will be returned. * If `X-Next-Token` is provided in the request headers but the token has

    expired, a response code of `409` will be returned. This is only applicable

    for some endpoints; see specific endpoint documentation below. #### X-Limit


    The page size can be controlled with the `X-Limit` header. Valid values are

    `1-100` and defaults to `100`. #### X-Next-Token


    If the results are paginated, a response header of `X-Next-Token` will be

    returned. Use the associated value in the subsequent request (via the `X-Next-Token`

    request header) to retrieve the next page. The following sequence diagram shows how to

    use `X-Next-Token` to fetch all the records. ## Chunked Uploads


    Uploads larger than `5MiB` (`5242880 bytes`) must be done in `5MiB` chunks

    (with the exception of the final chunk). Each chunk request MUST contain a

    `Content-Range` header specifying the portion of the upload, and a `Content-Type`

    header specifying binary content type (`application/octet-stream`). Range

    uploads must be contiguous. The maximum upload size is capped at `500MiB` (`524288000 bytes`). ## Chunked Downloads


    Downloads larger than `5MiB` (`5242880 bytes`) must be done in `1-5MiB`

    chunks (with the exception of the final chunk, which may be less than `1MiB`). Each chunk request MUST contain a `Range` header specifying the requested portion of the download,

    and an `Accept` header specifying binary and json content types (`application/octet-stream,application/json`)

    or all content types (`*/*`). ## Drivers


    If you need drivers to process agronomic data, download the ADAPT plugin below. We only support the plugin in the Windows environment, minimum is Windows 7 SP1. For asPlanted, asHarvested and asApplied data:

    * ADAPT Plugin


    Release notes can be found here. Download and use of the ADAPT plugin means that you agree to the EULA for use of the ADAPT plugin. Please review the EULA (last updated on June 6th, 2019) before download and use of the ADAPT plugin.'
  contact:
    name: Climate FieldView Support
    email: developer@climate.com
  version: 4.0.11
servers:
- url: https://platform.climate.com/
tags:
- name: Fields
  description: Field data endpoints.
paths:
  /v4/fields:
    get:
      summary: Retrieve list of Fields
      description: Retrieve list of **Fields**. Filter the results by field name if the `fieldName` query parameter is specified.
      operationId: fetchFields
      tags:
      - Fields
      security:
      - api_key: []
      - oauth2_authorization_code:
        - platform
        - fields:read
      parameters:
      - $ref: '#/components/parameters/X-Next-Token'
      - $ref: '#/components/parameters/X-Limit'
      - $ref: '#/components/parameters/OptionalFieldNamePrefix'
      responses:
        '200':
          $ref: '#/components/responses/FetchFieldsOk'
        '206':
          $ref: '#/components/responses/FetchFieldsPartial'
        '304':
          $ref: '#/components/responses/304'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /v4/fields/{fieldId}:
    get:
      summary: Retrieve a specific Field by ID
      description: Retrieve a given **Field** by ID.
      operationId: fetchFieldById
      tags:
      - Fields
      security:
      - api_key: []
      - oauth2_authorization_code:
        - platform
        - fields:read
      parameters:
      - $ref: '#/components/parameters/FieldId'
      responses:
        '200':
          $ref: '#/components/responses/FetchFieldByIdOk'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
components:
  responses:
    '503':
      description: Server Busy
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
            format: int32
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    FetchFieldsPartial:
      description: Partial Result
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
        X-Next-Token:
          description: Token used to fetch next batch of results.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fields'
    '404':
      description: Not Found
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    FetchFieldByIdOk:
      description: Returns the requested Field.
      headers:
        X-Http-Request-Id:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Field'
    '304':
      description: Not Modified
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
        X-Next-Token:
          description: A token which may be used to poll for updates.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Empty'
    '403':
      description: Forbidden
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '429':
      description: Too Many Requests
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    FetchFieldsOk:
      description: OK
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
        X-Next-Token:
          description: Token used to poll for updates.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fields'
    '400':
      description: Bad Input
      headers:
        X-Http-Request-Id:
          description: Unique identifier assigned to the request.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    X-Next-Token:
      name: X-Next-Token
      in: header
      description: Opaque string which allows for fetching the next batch of results.  Can be used to poll for changes.
      required: false
      schema:
        type: string
    OptionalFieldNamePrefix:
      in: query
      description: Optional prefix filter for field name. Must be at least 3 characters.
      name: fieldName
      required: false
      schema:
        type: string
    X-Limit:
      in: header
      name: X-Limit
      description: Max number of results to return per batch.  Must be between 1 and 100 inclusive.  Defaults to 100.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
    FieldId:
      in: path
      description: Unique identifier of the Field.
      name: fieldId
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    Field:
      description: Logical representation of a Field with a name.  Spatial attributes of the Field are provided in the Boundary.
      required:
      - id
      - name
      - boundaryId
      - resourceOwnerId
      - parent
      properties:
        id:
          description: Unique identifier for a Field.
          type: string
          format: uuid
        name:
          description: Name of the Field.
          type: string
        boundaryId:
          description: Unique identifier for the current Field's Boundary.
          type: string
          format: uuid
        resourceOwnerId:
          description: Unique identifier of the resource owner that owns the Field.
          type: string
          format: uuid
        parent:
          $ref: '#/components/schemas/Parent'
      example:
        id: 00000000-0000-0000-0000-000000000000
        name: Back Forty
        boundaryId: 00000000-0000-0000-0000-000000000000
        resourceOwnerId: 00000000-0000-0000-0000-000000000000
        parent:
          id: 00000000-0000-0000-0000-000000000000
          type: farm
    Error:
      type: object
      properties:
        error:
          type: object
          required:
          - id
          - code
          - message
          properties:
            id:
              type: string
              format: uuid
            code:
              type: string
            message:
              type: string
              description: Description of the error encountered.
    Empty:
      type: object
    Fields:
      description: A batch of field results
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Field'
    Parent:
      description: A minimal set of attributes regarding the parent of a farm organization.
      required:
      - id
      - type
      properties:
        id:
          description: Unique identifier for the parent of a farm organization.
          type: string
          format: uuid
        type:
          description: Type of the parent of a farm organization.
          type: string
          enum:
          - farm
  securitySchemes:
    oauth2_authorization_code:
      description: 'Log in with FieldView OAuth2 provider (Authorization Code Grant). Used to authorize the client (partner) and

        user. The *access_token* is required to be provided in the `Authorization` header on all calls to the FieldView

        APIs with the following format `Bearer $access_token`.'
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://climate.com/static/app-login/
          tokenUrl: https://api.climate.com/api/oauth/token
          scopes:
            platform: (DEPRECATED) Legacy scope used for some Platform APIs
            fields:read: Required for retrieving field and boundary information
            farmOrganizations:read: Required for retrieving farm organization information
            operations:read: Required for retrieving operation information
            resourceOwners:read: Required for retrieving resource owner information
            scouting:read: Required for retrieving user\'s scouting information
            exports:read: Required for requesting or retrieving exports
            fields:write: Required for uploading field boundaries
            imagery:write: Required for uploading imagery
            rx:write: Required for uploading prescriptions
            soil:write: Required for uploading soil sample results
            asApplied:read: Required for retrieving as applied data
            asApplied:write: Required for uploading application data
            asPlanted:read: Required for retrieving planting data
            asPlanted:write: Required for uploading planting data
            asHarvested:read: Required for retrieving harvest data
            asHarvested:write: Required for uploading harvest data
            diagnostics:read: Required for retrieving CNH machine diagnostic data
            plantingActivitySummary:read: Required for retrieving planting activity summary data
            customerInsights:read: Required for retrieving customer insights metrics data
            avroAgronomicData:read: Required for retrieving agronomic data
    api_key:
      description: 'API access key used to control throttling (429 responses).  This key is typically formatted:

        `partner-{name}-{uuid}`'
      type: apiKey
      name: X-Api-Key
      in: header
x-amazon-apigateway-api-key-source: AUTHORIZER
x-provenance:
  method: harvested
  publisher: Climate FieldView
  source: https://dev.fieldview.com/openapi/platform.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)