Open Well Data

Open Well Data API

Read-only catalogue metadata and links. Version 1.3.

What it is

This API answers queries over the Open Well Data catalogue: public subsurface data sources (wells, drilling, logs, seismic, production, regulation), the standardized collections published on Zenodo, the datasets that have a reader in the owd Python package, and the variable dictionary. It returns JSON metadata and links. It does not serve data files: they are downloaded from Zenodo or from openwelldata.org.

No key or account is needed; an optional API key raises the limits. Every successful answer carries a cite field with the licence and attribution of each source. The full description is in /v1/openapi.json (OpenAPI 3.1) and the terms of use are in /terms.

Endpoints

RouteAnswer
GET /v1Index: endpoints, limits and links
GET /v1/healthService status
GET /v1/sourcesSearch sources: q (English or Spanish), country, category, access, status, data_type, limit (up to 100), offset, format
GET /v1/sources/{id}One source record
GET /v1/collectionsStandardized collections: q, country, data_type, status, licence, commercial_use, copy_commercial_use, limit, offset, format
GET /v1/collections/{id}One collection, with its package files (name, bytes, sha256 and the direct Zenodo url of each file)
GET /v1/datasets, GET /v1/datasets/{id}Datasets with a reader: licence, policy, citation and how to load them
GET /v1/openapi.jsonOpenAPI 3.1 description
GET /terms, GET /docsTerms of use, and this page
GET /key, GET /key/delete, GET /privacyRequest an API key, delete it, and the privacy notice of the keys; see API keys
GET, PATCH, DELETE /v1/keys/meWith X-API-Key: what is kept about the key, withdraw a consent, delete it all
POST /mcpRemote MCP server (JSON-RPC 2.0, Streamable HTTP); see MCP

Only GET, HEAD and OPTIONS are accepted, plus POST on /mcp and the key routes. Any other method answers 405. Errors are JSON: {"error":{"code":"...","message":"..."}}.

Filters and formats

shell
# Collections whose source licence allows commercial use, as CSV (cite in the X-OWD-Cite header)
curl -s -D - "https://api.openwelldata.org/v1/collections?commercial_use=allowed&format=csv" -o collections.csv

Limits

API keys (optional)

Every route works without a key, with the limits above. An optional key raises them: 600 requests per minute instead of 60, up to 50,000 per UTC day, and limit up to 1,000 per page instead of 100. It changes nothing else: same routes, same answers, same licences.

shell
# The same routes, with your key in the header (never in the address)
curl -s -H "X-API-Key: $OWD_API_KEY" "https://api.openwelldata.org/v1/collections?limit=1000"

# What is kept about your key, withdraw the optional consents, or delete everything
curl -s -H "X-API-Key: $OWD_API_KEY" https://api.openwelldata.org/v1/keys/me
curl -s -X PATCH -H "X-API-Key: $OWD_API_KEY" -H "Content-Type: application/json" -d '{"list_organization":false,"statement":false}' https://api.openwelldata.org/v1/keys/me
curl -s -X DELETE -H "X-API-Key: $OWD_API_KEY" https://api.openwelldata.org/v1/keys/me
python
import os, urllib.request
req = urllib.request.Request("https://api.openwelldata.org/v1/sources?q=drilling&limit=1000",
                             headers={"X-API-Key": os.environ["OWD_API_KEY"], "User-Agent": "my-script/1.0"})
shell (Claude Code, MCP with a key)
claude mcp add --transport http owd https://api.openwelldata.org/mcp --header "X-API-Key: $OWD_API_KEY"

Citation and licences

Each source keeps its own licence and attribution terms. The cite field of every answer gives them, as the record states them, together with the DOI of the collection when it has one, the DOI of the catalogue and the preprint:

cite (shape)
"cite": {
  "how_to_cite": "Cite the original provider of each source you use, ...",
  "catalogue": { "doi": "10.5281/zenodo.23961755", "url": "https://doi.org/10.5281/zenodo.23961755", "citation": "...", "licence": "CC BY-NC 4.0 (...)" },
  "preprint": { "doi": "10.31223/X5NJ8V", "url": "https://doi.org/10.31223/X5NJ8V" },
  "collection": { "doi": "10.5281/zenodo....", "url": "https://doi.org/10.5281/zenodo...." },
  "source": { "licence": "...", "licence_url": "...", "attribution": "..." }
}

Examples

curl

shell
# Search sources (English or Spanish words)
curl -s "https://api.openwelldata.org/v1/sources?q=seismic&country=Norway&limit=5"

# One collection, with its Zenodo links and its cite field
curl -s "https://api.openwelldata.org/v1/collections/volve-production"

# Datasets with a reader, with licence and citation
curl -s "https://api.openwelldata.org/v1/datasets"

Python, standard library (urllib)

python
import json
import urllib.parse
import urllib.request

BASE = "https://api.openwelldata.org"

def get(path, **params):
    url = BASE + path + ("?" + urllib.parse.urlencode(params) if params else "")
    req = urllib.request.Request(url, headers={"User-Agent": "my-script/1.0"})
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.load(r)

data = get("/v1/sources", q="drilling", limit=5)
for s in data["sources"]:
    print(s["id"], "|", s["licence"], "|", s["url"])
print(data["cite"]["how_to_cite"])

Python, with the owd package (not yet on PyPI)

The owd.api module of the owd package wraps the same routes, pages through lists, waits on 429 and downloads collection files from Zenodo checking their sha256. It comes with version 1.4.0 of the openwelldata package, which is not yet on PyPI. Until then, the standard library example above needs nothing to install.

python
from owd.api import Client, cite

api = Client()                      # https://api.openwelldata.org; waits and retries on 429
page = api.search("seismic", country="Norway", limit=5)
for s in page:
    print(s["id"], s["licence"])

col = api.collection("volve-production")
for f in col.files():               # name, bytes, sha256 and Zenodo link of each file
    print(f["name"], f["bytes"], f["sha256"])
print(cite(col)["source"])          # licence and attribution of the source

R, httr2

r
library(httr2)

resp <- request("https://api.openwelldata.org/v1/sources") |>
  req_url_query(q = "seismic", country = "Norway", limit = 5) |>
  req_user_agent("my-script (R httr2)") |>
  req_retry(max_tries = 3) |>       # waits on 429 using Retry-After
  req_perform()

x <- resp_body_json(resp)
sapply(x$sources, function(s) s$id)
x$cite$how_to_cite

R, jsonlite

r
library(jsonlite)

x <- fromJSON("https://api.openwelldata.org/v1/collections?data_type=well_logs&limit=10")
x$collections[, c("id", "name", "country")]

MCP (remote server)

https://api.openwelldata.org/mcp (exactly, without a trailing slash) is a remote MCP server for AI assistants. Transport: Streamable HTTP, JSON-RPC 2.0 by POST, answered in plain JSON (no SSE stream, no sessions). It answers initialize, ping, tools/list and tools/call; notifications get 202. GET on /mcp answers 405. Every tool is read-only and every tool result carries cite.

Claude Code

shell
claude mcp add --transport http owd https://api.openwelldata.org/mcp

Claude Desktop

Settings, Connectors, Add custom connector, and give the address https://api.openwelldata.org/mcp. No authentication is needed. With an API key, clients that can send headers add X-API-Key.

Other clients

Any MCP client with the Streamable HTTP transport works with the address above. Many read a JSON configuration like this one (the exact key names depend on the client):

json
{
  "mcpServers": {
    "owd": { "type": "http", "url": "https://api.openwelldata.org/mcp" }
  }
}

By hand, with curl:

shell
# initialize
curl -s -X POST https://api.openwelldata.org/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

# list the tools
curl -s -X POST https://api.openwelldata.org/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# call one tool
curl -s -X POST https://api.openwelldata.org/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_sources","arguments":{"text":"pozos","limit":3}}}'

Arguments that do not match the input schema of a tool give a tool result with isError: true and the reason, so the assistant can correct the call. search_sources and search_collections take q as an alias of text.

Tools

ToolWhat it returns
search_sourcesSearch the catalogue of public data sources of the sector (wells, drilling, seismic, production, regulation, software). `text`: words that must all appear; English or Spanish, with or without accents (sísmica = seismic). Returns the records (id, url, licence, verification status) and `cite`.
get_sourceOne source record, as published in data/source/<id>.json, with `cite`.
search_collectionsStandardized collections (packages on Zenodo), with their DOI and links when published. Same filters as the /v1/collections route.
get_collectionOne collection with its package files (name, bytes, sha256 and direct Zenodo link of each file) and `cite`.
list_datasetsDatasets with their own reader in the owd Python package: id, name, licence, policy (copy/recipe/link), citation and whether the reader is tested.
describe_datasetEverything about a dataset: source, licence, citation, format and how to load it with owd.load.
citeThe citation block of one source, collection or dataset: licence, attribution, collection DOI, catalogue DOI and preprint.
variablesThe Open Well Data variable dictionary (logs, drilling, production, pvt, core, well_test...): name, family, dimension, unit, whether it is a standard channel and its common mnemonics.
standard_channelsOpen Well Data standard channels (e.g. hookload, wob, gr, rhob) with their standard unit (SI where applicable) and the names (aliases, lower case) that sources use for them.
standard_nameTranslate a channel name from any source (HKLD, 'Hook Load (klbs)', WOB...) to its standard name, or null.
search_by_variablesWells and files that have ALL the requested variables (e.g. ["gr", "rhob", "dt"]) in the published variable index, with the licence and policy of their dataset. The index has no depth or time intervals. To read a file: owd.load(dataset, file).

The mnemonic lookup tools of the local server (lookup_mnemonic, variable_variants) are not in the remote server yet: they need the full mnemonic index (1.7 MB). They work with the local server of the owd package and on the dictionary page of the site.

Contact

contact@openwelldata.org. Terms of use: /terms. OpenAPI: /v1/openapi.json.