{
 "openapi": "3.1.0",
 "info": {
  "title": "Township Converter API",
  "version": "1.0.0",
  "description": "Convert US PLSS, Canadian DLS/LSD, BC NTS and NWT/Nunavut/Yukon grid land descriptions to latitude/longitude and UTM, and back. Results are for reference, not a legal survey. If the deployment sets API_KEYS, send X-API-Key."
 },
 "servers": [
  {
   "url": "https://townshipconverter.app"
  }
 ],
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   }
  },
  "schemas": {
   "Result": {
    "type": "object",
    "properties": {
     "input": {
      "type": "string"
     },
     "ok": {
      "type": "boolean"
     },
     "system": {
      "type": "string"
     },
     "direction": {
      "type": "string",
      "enum": [
       "forward",
       "reverse"
      ]
     },
     "latitude": {
      "type": "number"
     },
     "longitude": {
      "type": "number"
     },
     "utm": {
      "type": "object",
      "properties": {
       "zone": {
        "type": "integer"
       },
       "band": {
        "type": "string"
       },
       "easting": {
        "type": "integer"
       },
       "northing": {
        "type": "integer"
       },
       "text": {
        "type": "string"
       }
      }
     },
     "dms": {
      "type": "string"
     },
     "description": {
      "type": [
       "string",
       "null"
      ]
     },
     "us_plss": {
      "type": [
       "string",
       "null"
      ]
     },
     "us_plss_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "us_plss_text": {
      "type": [
       "string",
       "null"
      ]
     },
     "dls_quarter": {
      "type": [
       "string",
       "null"
      ]
     },
     "dls_lsd": {
      "type": [
       "string",
       "null"
      ]
     },
     "bc_nts": {
      "type": [
       "string",
       "null"
      ]
     },
     "nwt_grid": {
      "type": [
       "string",
       "null"
      ]
     },
     "bounds": {
      "type": [
       "object",
       "null"
      ],
      "properties": {
       "south": {
        "type": "number"
       },
       "west": {
        "type": "number"
       },
       "north": {
        "type": "number"
       },
       "east": {
        "type": "number"
       }
      }
     },
     "near": {
      "type": [
       "object",
       "null"
      ],
      "properties": {
       "town": {
        "type": "string"
       },
       "distance_km": {
        "type": "number"
       },
       "direction": {
        "type": "string"
       },
       "text": {
        "type": "string"
       }
      }
     },
     "precision": {
      "type": [
       "string",
       "null"
      ]
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "error": {
      "type": "string"
     }
    }
   }
  }
 },
 "security": [
  {},
  {
   "apiKey": []
  }
 ],
 "paths": {
  "/api/convert": {
   "get": {
    "summary": "Convert one location",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "NW 32 38 08 W3"
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     }
    }
   },
   "post": {
    "summary": "Convert up to 1000 locations",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "queries": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "maxItems": 1000
         }
        }
       },
       "example": {
        "queries": [
         "NW 32 38 08 W3",
         "Sec 14 T2N R68W 6th PM CO",
         "52.3155, -107.1128"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Results",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "count": {
           "type": "integer"
          },
          "ok": {
           "type": "integer"
          },
          "results": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Result"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/reverse": {
   "get": {
    "summary": "Land description at a point",
    "parameters": [
     {
      "name": "lat",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number"
      },
      "example": 52.3155
     },
     {
      "name": "lon",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number"
      },
      "example": -107.1128
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     }
    }
   }
  },
  "/api/geocode": {
   "get": {
    "summary": "Address / place search (US + Canada)",
    "security": [
     {}
    ],
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "Main Street, Langham SK"
     }
    ],
    "responses": {
     "200": {
      "description": "Matches",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "results": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "name": {
              "type": "string"
             },
             "lat": {
              "type": "number"
             },
             "lon": {
              "type": "number"
             },
             "type": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/share": {
   "post": {
    "summary": "Create a team share link",
    "security": [
     {}
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "title": {
          "type": "string"
         },
         "rows": {
          "type": "array",
          "items": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Created {id}"
     },
     "501": {
      "description": "Storage not configured"
     }
    }
   },
   "get": {
    "summary": "Read a shared list",
    "security": [
     {}
    ],
    "parameters": [
     {
      "name": "id",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Shared data"
     },
     "404": {
      "description": "Expired"
     }
    }
   }
  },
  "/api/health": {
   "get": {
    "summary": "Service status",
    "security": [
     {}
    ],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/mcp": {
   "post": {
    "summary": "MCP endpoint for AI assistants (JSON-RPC 2.0, Streamable HTTP)",
    "responses": {
     "200": {
      "description": "JSON-RPC response"
     }
    }
   }
  },
  "/api/wells": {
   "get": {
    "summary": "Open well data (BC Energy Regulator, Government of Saskatchewan)",
    "parameters": [
     {
      "name": "bbox",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "example": "-120.30,56.20,-120.10,56.32",
      "description": "west,south,east,north \u2014 max 0.6\u00b0 per side"
     },
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "UWI, licence / WA number or well name"
     }
    ],
    "security": [
     {}
    ],
    "responses": {
     "200": {
      "description": "Wells",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "count": {
           "type": "integer"
          },
          "wells": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "src": {
              "type": "string"
             },
             "lat": {
              "type": "number"
             },
             "lon": {
              "type": "number"
             },
             "uwi": {
              "type": "string"
             },
             "licence": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "status": {
              "type": "string"
             },
             "class": {
              "type": "string",
              "enum": [
               "active",
               "drilling",
               "suspended",
               "abandoned",
               "orphan",
               "other"
              ]
             },
             "operator": {
              "type": "string"
             },
             "fluid": {
              "type": "string"
             },
             "field": {
              "type": "string"
             },
             "spud": {
              "type": "string"
             },
             "depth": {
              "type": "string"
             },
             "attrs": {
              "type": "object"
             }
            }
           }
          },
          "attribution": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "notes": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  }
 }
}