OlmoEarth API

What is OlmoEarth API and when should you use it?

OlmoEarth API is a hosted REST API from the Allen Institute for Artificial Intelligence, commonly known as Ai2. It is designed for Earth-observation and geospatial machine-learning workflows rather than general conversational AI. A REST API is a web service that applications call over HTTP; requests and responses are exchanged as JSON data.

The platform can be used to manage geographic areas, create datasets, run fine-tuned models, generate embeddings, and retrieve predictions. An area is represented with GeoJSON geometry, such as a Polygon or MultiPolygon using WGS84 coordinates. This makes OlmoEarth relevant to applications that analyze regions on Earth rather than applications that need a general-purpose text assistant.

Ai2's broader developer ecosystem includes open Olmo language models, Molmo multimodal models, Tülu, and related research artifacts. Those models are generally downloaded and run locally or deployed through infrastructure chosen by the developer. Ai2 does not present a single general-purpose hosted language-model API comparable to a standard chat-completions service. Use OlmoEarth when you need its hosted geospatial workflows; use Ai2's open-model documentation when you intend to control the model deployment yourself.

Who is the API for?

OlmoEarth is suited to developers, research teams, and organizations building applications around satellite or other Earth-observation data, geographic regions, geospatial datasets, model fine-tuning, embeddings, and prediction retrieval. Familiarity with HTTP requests, JSON, and basic GeoJSON is helpful, but you do not need to be an expert in machine learning to make an initial API request.

It is a poor fit if your main requirement is a hosted chatbot, generic text generation, a unified image-generation service, or a conventional assistant API with conversation state and tool calling. Ai2's open models may support broader applications when deployed with suitable infrastructure, but those capabilities should not be assumed to be available through OlmoEarth.

Getting access and obtaining an API key

OlmoEarth uses account-based access. Ai2 describes the platform as available now and directs prospective users to request access. After access is granted, authentication uses a bearer token created in OlmoEarth Studio.

API keys can be created, renamed, and revoked from the user's profile. The documentation states that an account can have up to 10 keys. Store the key as a server-side environment variable, such as OLMOEARTH_API_KEY. Do not place it in browser JavaScript, mobile application code, public repositories, or client-side HTML, because anyone who can inspect that code could copy the credential.

The key is sent in an HTTP header using the standard bearer-token format:

Authorization: Bearer YOUR_OLMOEARTH_API_KEY

Open Ai2 model downloads and local execution generally do not require an Ai2 inference API key. Separate access requirements can still apply to particular datasets, gated repositories, hosted demonstrations, or third-party inference services.

Choosing the appropriate Ai2 API or model path

An OpenAI-compatible server shown in an Ai2 deployment example is not automatically an Ai2-managed endpoint. Before integrating, verify the server operator, base URL, authentication method, available model, service terms, and operational limits.

Making your first OlmoEarth API request

The documented API base URL is https://olmoearth.allenai.org/api/v1/. The following example creates an area with a GeoJSON Polygon. The coordinates use longitude and latitude in WGS84 order, and the polygon closes by repeating its first coordinate.

set -euo pipefail

: "${OLMOEARTH_API_KEY:?Set OLMOEARTH_API_KEY first}"

curl --fail-with-body --silent --show-error 
  --request POST 
  "https://olmoearth.allenai.org/api/v1/areas" 
  --header "Authorization: Bearer ${OLMOEARTH_API_KEY}" 
  --header "Content-Type: application/json" 
  --data '{
    "name": "Nandi County Research Site",
    "geom": {
      "type": "Polygon",
      "coordinates": [[
        [35.1000, 0.1000],
        [35.2000, 0.1000],
        [35.2000, 0.2000],
        [35.1000, 0.2000],
        [35.1000, 0.1000]
      ]]
    }
  }'

Before running it, set the key in your shell:

export OLMOEARTH_API_KEY='replace-with-your-key'

The corresponding Python example uses the widely supported requests HTTP library. It keeps the key outside the source code and applies a timeout so the process does not wait indefinitely for a network response.

# Install: pip install requests
import os
import sys
import requests

api_key = os.environ.get("OLMOEARTH_API_KEY")
if not api_key:
    raise SystemExit("Set OLMOEARTH_API_KEY before running this script")

url = "https://olmoearth.allenai.org/api/v1/areas"
payload = {
    "name": "Nandi County Research Site",
    "geom": {
        "type": "Polygon",
        "coordinates": [[
            [35.1000, 0.1000],
            [35.2000, 0.1000],
            [35.2000, 0.2000],
            [35.1000, 0.2000],
            [35.1000, 0.1000],
        ]],
    },
}

try:
    response = requests.post(
        url,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
except requests.HTTPError as exc:
    print(f"HTTP error: {exc}", file=sys.stderr)
    print(response.text, file=sys.stderr)
    raise SystemExit(1)
except requests.RequestException as exc:
    print(f"Request failed: {exc}", file=sys.stderr)
    raise SystemExit(1)

print(response.json())

Understanding the response

A successful request returns JSON from the API. The supplied integration example checks for a records array and reads the identifier of the first created area. The exact response fields should be confirmed in the live API reference, because schemas can change as the platform develops.

Always check the HTTP status before treating a response as successful. In production code, log useful request identifiers and safe error details, but never log the API key. For failed requests, preserve the response body during development because it may explain validation, authentication, or access problems.

After creating an area, the documented area-management operations include retrieving a specific area with GET /areas/{area_id}, searching areas with POST /areas/search, updating one with PUT /areas/{area_id}, and deleting one with DELETE /areas/{area_id}. The interactive API browser can be used to inspect current schemas and try requests.

How pricing and access generally work

No public standard per-token, per-request, or subscription price was identified for OlmoEarth in the reviewed official documentation. Access is request-based through an account, and prospective users may need to request platform access.

Ai2 also does not publish a unified token-pricing table for a general hosted language-model API in the reviewed materials. Open model downloads and self-managed execution may avoid a hosted Ai2 inference charge, but they still require the developer to provide suitable compute, storage, networking, and operations. If a third-party provider hosts an Ai2 model, that provider's pricing and terms apply.

Confirm current commercial terms, quotas, and account-specific conditions before committing a production workload. Do not estimate costs from token pricing used by another provider.

Capabilities: what is and is not documented

The clearest documented OlmoEarth capabilities are:

• Authenticated REST and JSON requests.
• Geographic area creation, retrieval, search, update, and deletion.
• GeoJSON Polygon and MultiPolygon area definitions using WGS84 coordinates.
• Programmatic dataset creation.
• Execution of fine-tuned models.
• Embedding generation.
• Prediction retrieval.

The reviewed documentation does not verify the following as OlmoEarth features:

• Chat streaming.
• Function calling or tool calling.
• Persistent assistants or conversation memory.
• Structured text-output schemas or a separate JSON mode.
• Generic image or file uploads in the way commonly offered by generative AI APIs.
• Web search.

These unverified items should be treated as unknown rather than as unsupported forever; check the current API reference for changes. Ai2's open models can be used in multimodal or tool-using systems when developers supply the model deployment and surrounding application infrastructure, but that does not establish the same capability for OlmoEarth.

SDKs, API reference, and playground tools

No provider-specific official SDK was identified in the reviewed materials. Standard HTTP clients such as curl, Python requests, JavaScript HTTP libraries, or PHP cURL are therefore practical integration choices.

OlmoEarth's interactive API browser is the main developer aid. It provides endpoint schemas, lets an authenticated user inspect and try requests, and can generate client code for common languages and libraries. Use it to confirm request and response fields instead of copying assumptions from unrelated AI APIs.

The API reference is available at docs.olmoearth.allenai.org/api/. The documentation site and OlmoEarth Studio should be treated as the source of truth for current access requirements and endpoint behavior.

Advanced integration patterns

Manage an area as a resource

A typical application can create an area once, retain the returned identifier, and use that identifier in later workflows. Retrieve the resource when displaying its current state, use the search endpoint when locating existing areas, and update or delete it only after confirming the intended account and area identifier.

curl --fail-with-body --silent --show-error 
  --request GET 
  "https://olmoearth.allenai.org/api/v1/areas/AREA_ID" 
  --header "Authorization: Bearer ${OLMOEARTH_API_KEY}" 
  --header "Accept: application/json"

The exact search payload and response schema should be taken from the current interactive API reference. Avoid inventing fields based on conventions from another geospatial API.

Separate platform operations from application logic

For a production service, keep OlmoEarth calls behind a server-side application layer. That layer can validate GeoJSON before submission, associate platform resource identifiers with internal records, retry safe requests, and prevent users from accessing credentials. It can also distinguish temporary network failures from permanent validation or authorization errors.

Dataset preparation, fine-tuning, embedding generation, and prediction retrieval are separate concerns even when they form one application workflow. Track each operation's status and preserve enough metadata to reproduce which area, dataset, model, and parameters produced a result.

Limits and production considerations

Public numeric rate limits were not identified in the reviewed OlmoEarth documentation. There is also no public latency target, service tier, or service-level agreement identified there. Performance can vary with the geographic area, dataset, model, and inference operation.

Use bounded timeouts, check HTTP status codes, and apply exponential backoff only where retrying is safe. Mutating operations such as creation and updates can produce duplicates if blindly retried after a network timeout, so add application-level idempotency safeguards or reconcile the resource afterward.

The reviewed documentation does not provide a complete retention schedule, deletion service-level agreement, or default storage period for submitted datasets, areas, predictions, or API logs. Review the current platform agreement and privacy documentation before sending sensitive or confidential material. Also check model cards, dataset cards, responsible-use guidance, and license restrictions; some Ai2 artifacts may have academic, noncommercial, or other usage conditions.

Do not assume that a local or third-party deployment has the same uptime, rate limits, streaming behavior, tool support, or data-retention policy as OlmoEarth. Those characteristics belong to the actual service operator.

When OlmoEarth API is a good or poor choice

OlmoEarth is a good choice when an application needs Ai2-hosted geospatial resources and workflows, especially area management, Earth-observation datasets, fine-tuned geospatial models, embeddings, or predictions. It is also a reasonable starting point for a research prototype that can use REST and GeoJSON and does not require a published token-pricing model or public numeric quotas.

It is a poor choice when the core requirement is a general hosted chat API, guaranteed streaming, function calling, persistent assistants, web search, or a documented generic file-upload interface. It may also be unsuitable when an organization needs public SLA commitments, published rate limits, a provider-maintained SDK, or clearly defined data-retention terms that are not available in the reviewed documentation.

The main architectural decision is whether to use a specialized hosted geospatial platform or deploy an open Ai2 model yourself. Make that choice based on the workload, required control, operational budget, data constraints, and the exact capabilities documented for the service you will run.