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
| Route | Answer |
|---|---|
GET /v1 | Index: endpoints, limits and links |
GET /v1/health | Service status |
GET /v1/sources | Search 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/collections | Standardized 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.json | OpenAPI 3.1 description |
GET /terms, GET /docs | Terms of use, and this page |
GET /key, GET /key/delete, GET /privacy | Request an API key, delete it, and the privacy notice of the keys; see API keys |
GET, PATCH, DELETE /v1/keys/me | With X-API-Key: what is kept about the key, withdraw a consent, delete it all |
POST /mcp | Remote 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
licence: an SPDX id (for exampleCC-BY-4.0,NLOD-2.0,CC0-1.0) or a licence family:cc0,cc-by,cc-by-sa,cc-by-nd,cc-by-nc,cc-by-nc-sa,cc-by-nc-nd,nlod,ogl-uk,ogl-alberta,odbl,public-domain,equinor-volve,apache,mit,gpl,lgpl,other. For collections, the SPDX ids and families are read from the licence name of the source (source_licence).commercial_use=allowed|not_allowed|unknown. Collections: the licence of the source data, by family (CC BY, CC BY-SA, CC BY-ND, CC0, NLOD, the government licences of the UK and Alberta, ODbL, public domain and the Equinor Volve terms giveallowed; any NC licence givesnot_allowed; terms of a provider without a named licence giveunknown).copy_commercial_useapplies the same rule to the licence of the Open Well Data copy on Zenodo. These values only restate the licence; the licence text and the conditions of each source (for example, no resale) prevail.format=csvon/v1/sourcesand/v1/collections: the same page as in JSON, as RFC 4180 CSV with a fixed header row, UTF-8 and CRLF. CSV carries the cite in theX-OWD-Citeheader (JSON), the licence inX-OWD-Licence, andLinkwithrel="cite-as"andrel="license".
# 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.csvLimits
- 60 requests per minute per client, counted together for the routes and for
/mcp. Over the limit the answer is 429 with aRetry-Afterheader: wait that number of seconds and try again. limitis at most 100 per page; useoffsetto page through a list. The search text is cut to 200 characters.- With an optional API key: 600 requests per minute, 50,000 per UTC day and
limitup to 1,000. - The body of a request to
/mcpis at most 64 kB. - Answers of the GET routes may be cached by the browser for 5 minutes; the catalogue files are read from the site and kept for up to 10 minutes.
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.
- Request one at /key (no cost): an email address, which is verified with a link valid for 24 hours, the type of organization, the country and the intended use. The organization and two consents are optional and unticked. The key is shown once; it cannot be recovered, only replaced by requesting a new one.
- Use it in the
X-API-Keyheader, also onPOST /mcp. A key in the address (?key=owd_...,?api_key=owd_...) answers 400key_in_url, because addresses end up in logs. An unknown key answers 401invalid_key; a request with the header empty is a request without a key. - Limits: over the per-minute limit, 429
rate_limitedwithRetry-After: 60; over the daily limit, 429daily_limitwithRetry-Afterup to 00:00 UTC. The well search keeps its limits on tiles per request with or without a key. - Your data:
GET /v1/keys/meshows everything kept about the key;PATCH /v1/keys/mewith{"list_organization":false}and/or{"statement":false}withdraws a consent;DELETE /v1/keys/me, or /key/delete without the key, deletes the key and everything linked to it. A key unused for 18 months is deleted; we try to send a notice by email 30 days before, and the deletion does not wait for it. Details: /privacy.
# 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/meimport 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"})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": {
"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": "..." }
}- Each source:
cite.sourcefor one record, orcite.items[]for a list, withlicence,licence_urlandattribution. Follow them when you use the source, and cite its original provider. - Collections: cite the Zenodo DOI of the collection (
cite.collection) and the original source. - Volve: Volve data are shared under the Equinor Volve data licence (Equinor HRS terms and conditions for licence to data - Volve): terms (PDF). Credit: Equinor ASA and the former Volve licence partners, ExxonMobil Exploration & Production Norway AS and Bayerngas Norge AS. The data may not be sold. Answers that hold Volve records give these terms and never a Creative Commons licence.
- The catalogue: Delgado-Uriarte, D. (2026). Open Well Data catalogue [Data set]. Zenodo. https://doi.org/10.5281/zenodo.23961755. The catalogue records are under CC BY-NC 4.0; commercial use of the catalogue needs prior written permission (contact@openwelldata.org).
- Preprint: https://doi.org/10.31223/X5NJ8V.
Examples
curl
# 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)
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.
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 sourceR, httr2
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_citeR, jsonlite
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
claude mcp add --transport http owd https://api.openwelldata.org/mcpClaude 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):
{
"mcpServers": {
"owd": { "type": "http", "url": "https://api.openwelldata.org/mcp" }
}
}By hand, with curl:
# 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
| Tool | What it returns |
|---|---|
search_sources | Search 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_source | One source record, as published in data/source/<id>.json, with `cite`. |
search_collections | Standardized collections (packages on Zenodo), with their DOI and links when published. Same filters as the /v1/collections route. |
get_collection | One collection with its package files (name, bytes, sha256 and direct Zenodo link of each file) and `cite`. |
list_datasets | Datasets with their own reader in the owd Python package: id, name, licence, policy (copy/recipe/link), citation and whether the reader is tested. |
describe_dataset | Everything about a dataset: source, licence, citation, format and how to load it with owd.load. |
cite | The citation block of one source, collection or dataset: licence, attribution, collection DOI, catalogue DOI and preprint. |
variables | The 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_channels | Open 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_name | Translate a channel name from any source (HKLD, 'Hook Load (klbs)', WOB...) to its standard name, or null. |
search_by_variables | Wells 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.