{
  "openapi": "3.1.0",
  "info": {
    "title": "Royalty Clerk: Texas wells near a place",
    "version": "1.0.0",
    "summary": "Oil and gas wells, their status and drilling permits near a Texas town, county, ZIP code or point.",
    "description": "Oil and gas wells near a Texas place, from Railroad Commission of Texas records: located wells within 1, 3, 10 miles by status (producing, idle, plugged), the 10 nearest wells (API number, operator, lease, distance), drilling permits of the last 12 months within 10 miles with the newest 10, the data date, a link to the place's page and the credit line to show. Give exactly one place: town, county, zip, or lat and lon. Street addresses are not accepted.\n\nFree, no key. Limits: 60 answers an hour per client address (429 with Retry-After past it); every answer is the same for everyone and cached (public, max-age=3600, s-maxage=21600, stale-while-revalidate=86400). Show the credit line \"Source: Railroad Commission of Texas · Map: Royalty Clerk\" with a link to links.page wherever the figures appear. The same answer is the tool wells_near of the Model Context Protocol server at https://royaltyclerk.com/api/public/mcp. Plain counts of the state's records.",
    "termsOfService": "https://royaltyclerk.com/terms"
  },
  "externalDocs": {
    "description": "Examples and terms",
    "url": "https://royaltyclerk.com/wells-near-api"
  },
  "servers": [
    {
      "url": "https://royaltyclerk.com"
    }
  ],
  "paths": {
    "/api/public/wells-near": {
      "get": {
        "operationId": "wellsNear",
        "summary": "Wells near a Texas place",
        "description": "Name exactly one place: town, county, zip, or lat and lon together. Any other parameter is refused (400).",
        "parameters": [
          {
            "name": "town",
            "in": "query",
            "required": false,
            "description": "A Texas town by name or page name: Midland, Karnes City, midland-tx.",
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "county",
            "in": "query",
            "required": false,
            "description": "A Texas county by name or 5-digit FIPS code: Karnes, Karnes County, 48255.",
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "description": "A Texas ZIP code: 79701.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{5}$"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "description": "Latitude in decimal degrees, with lon. Rounded to two decimals (about a kilometre).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": false,
            "description": "Longitude in decimal degrees, with lat.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The answer.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "public, max-age=3600, s-maxage=21600, stale-while-revalidate=86400"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellsNearAnswer"
                }
              }
            }
          },
          "400": {
            "description": "No place, more than one, a street address, an unknown parameter, or a value this service cannot read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such town or ZIP code on file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many answers for this client address in the last hour.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before asking again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The service is busy or the data cannot be read just now; nothing is cached.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before asking again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WellsNearAnswer": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "place",
          "rings",
          "area",
          "nearest",
          "permits",
          "data",
          "credit",
          "links"
        ],
        "properties": {
          "place": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "type",
              "query",
              "name",
              "county",
              "lat",
              "lon"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "town",
                  "county",
                  "zip",
                  "point"
                ]
              },
              "query": {
                "type": "string",
                "description": "The place as this service reads it, such as town=midland-tx or lat=31.99&lon=-102.08 (points are rounded to two decimals)."
              },
              "name": {
                "type": "string"
              },
              "county": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The county the place lies in, such as Midland County."
              },
              "lat": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The point the circles are drawn around; null for a county."
              },
              "lon": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          "rings": {
            "type": "array",
            "description": "Located wells within 1, 3, 10 miles of the point, by status; each circle includes the smaller ones. Empty for a county.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "miles",
                "wells",
                "producing",
                "idle",
                "plugged"
              ],
              "properties": {
                "miles": {
                  "type": "number"
                },
                "wells": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Located wells"
                },
                "producing": {
                  "type": "integer",
                  "minimum": 0
                },
                "idle": {
                  "type": "integer",
                  "minimum": 0
                },
                "plugged": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "area": {
            "type": [
              "object",
              "null"
            ],
            "description": "Inside the county line or the ZIP code's Census outline: wells by status, and drilling permits issued in the last 12 months. Null for a town or a point.",
            "additionalProperties": false,
            "required": [
              "wells",
              "producing",
              "idle",
              "plugged",
              "permits"
            ],
            "properties": {
              "wells": {
                "type": "integer",
                "minimum": 0,
                "description": "Located wells"
              },
              "producing": {
                "type": "integer",
                "minimum": 0
              },
              "idle": {
                "type": "integer",
                "minimum": 0
              },
              "plugged": {
                "type": "integer",
                "minimum": 0
              },
              "permits": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "nearest": {
            "type": "array",
            "maxItems": 10,
            "description": "The 10 located wells nearest the point, nearest first. Empty for a county.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "api",
                "status",
                "operator",
                "lease",
                "miles",
                "lat",
                "lon"
              ],
              "properties": {
                "api": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "API number, such as 42-329-12345."
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "producing",
                    "idle",
                    "plugged"
                  ],
                  "description": "producing: on a lease the state's production records list as producing; idle: any other well not plugged; plugged: plugged on the state's records."
                },
                "operator": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "lease": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "miles": {
                  "type": "number",
                  "description": "Distance from the point, in miles."
                },
                "lat": {
                  "type": "number"
                },
                "lon": {
                  "type": "number"
                }
              }
            }
          },
          "permits": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "months",
              "miles",
              "count",
              "newest"
            ],
            "description": "Drilling permits issued in the last 12 months within 10 miles of the point (in the county, for a county).",
            "properties": {
              "months": {
                "type": "integer",
                "minimum": 0
              },
              "miles": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "count": {
                "type": "integer",
                "minimum": 0
              },
              "newest": {
                "type": "array",
                "maxItems": 10,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "api",
                    "issued",
                    "operator",
                    "lease",
                    "type",
                    "horizontal",
                    "miles"
                  ],
                  "properties": {
                    "api": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "issued": {
                      "type": "string",
                      "format": "date"
                    },
                    "operator": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "lease": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "type": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The permit's purpose as the state files it, such as new drill."
                    },
                    "horizontal": {
                      "type": [
                        "boolean",
                        "null"
                      ]
                    },
                    "miles": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "date",
              "newestPermit",
              "source",
              "sourceUrl"
            ],
            "properties": {
              "date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The day the newest Railroad Commission well or permit file behind these figures was loaded (YYYY-MM-DD)."
              },
              "newestPermit": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The newest permit date on file."
              },
              "source": {
                "type": "string"
              },
              "sourceUrl": {
                "type": "string"
              }
            }
          },
          "credit": {
            "type": "string",
            "const": "Source: Railroad Commission of Texas · Map: Royalty Clerk",
            "description": "Show this line, with a link to links.page, wherever the figures are shown."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "page",
              "map",
              "docs"
            ],
            "properties": {
              "page": {
                "type": "string",
                "description": "The Royalty Clerk page for the place."
              },
              "map": {
                "type": "string",
                "description": "The live well map, opened on the place."
              },
              "docs": {
                "type": "string"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "A short code, such as bad_zip or limited."
          },
          "message": {
            "type": "string"
          },
          "docs": {
            "type": "string"
          }
        }
      }
    }
  }
}