{
 "openapi": "3.1.0",
 "info": {
  "title": "Political Gadgets - Find My Electorates",
  "version": "2026-11-05",
  "description": "Look up the federal division, state or territory electorate and local council area for an Australian postcode, street address or coordinate. Free, no API key, CORS open. Postcodes can span several electorates, so postcode results are lists with share_percent. Boundaries are simplified (about 40 m); not for official use. More detail for agents: https://politicalgadgets.com/electorate_finder/llms.txt",
  "contact": {
   "name": "Political Gadgets",
   "url": "https://politicalgadgets.com/"
  }
 },
 "externalDocs": {
  "description": "Guide for agents",
  "url": "https://politicalgadgets.com/electorate_finder/llms.txt"
 },
 "servers": [
  {
   "url": "https://politicalgadgets.com"
  }
 ],
 "paths": {
  "/electorate_finder/electorate_lookup.php": {
   "get": {
    "operationId": "lookupElectorates",
    "summary": "Find electorates by postcode or by latitude/longitude",
    "description": "Give EITHER postcode OR lat+lon. With postcode the result lists every federal, state and council area the postcode overlaps (with share_percent). With lat+lon the result is the single area at each level the point falls in; pass rings=0 to omit map polygons. Unknown postcode: ok=true, found=false.",
    "parameters": [
     {
      "name": "postcode",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "pattern": "^[0-9]{4}$"
      },
      "description": "4-digit Australian postcode, e.g. 2000 (keep leading zeros, e.g. 0800).",
      "example": "2040"
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "example": -33.8688
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "example": 151.2093
     },
     {
      "name": "rings",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "enum": [
        0,
        1
       ]
      },
      "description": "Use 0 with lat/lon to leave out the polygon arrays (recommended)."
     }
    ],
    "responses": {
     "200": {
      "description": "Result (postcode mode or point mode), or ok=false with an error for bad input.",
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "type": "object",
           "properties": {
            "ok": {
             "type": "boolean"
            },
            "found": {
             "type": "boolean"
            },
            "postcode": {
             "type": "string"
            },
            "state_code": {
             "type": "string"
            },
            "federal": {
             "type": "array",
             "items": {
              "type": "object",
              "properties": {
               "name": {
                "type": "string"
               },
               "share_percent": {
                "type": "integer",
                "description": "Approximate share of the postcode's area."
               },
               "member": {
                "type": [
                 "string",
                 "null"
                ],
                "description": "Current member, e.g. 'Name (ALP)'. Federal only; null for state and council."
               },
               "url": {
                "type": "string",
                "format": "uri",
                "description": "Political Gadgets page for this area."
               }
              }
             },
             "description": "Federal divisions (House of Representatives), largest share first."
            },
            "state": {
             "type": "array",
             "items": {
              "type": "object",
              "properties": {
               "name": {
                "type": "string"
               },
               "share_percent": {
                "type": "integer",
                "description": "Approximate share of the postcode's area."
               },
               "member": {
                "type": [
                 "string",
                 "null"
                ],
                "description": "Current member, e.g. 'Name (ALP)'. Federal only; null for state and council."
               },
               "url": {
                "type": "string",
                "format": "uri",
                "description": "Political Gadgets page for this area."
               }
              }
             },
             "description": "State or territory lower-house electorates."
            },
            "council": {
             "type": "array",
             "items": {
              "type": "object",
              "properties": {
               "name": {
                "type": "string"
               },
               "share_percent": {
                "type": "integer",
                "description": "Approximate share of the postcode's area."
               },
               "member": {
                "type": [
                 "string",
                 "null"
                ],
                "description": "Current member, e.g. 'Name (ALP)'. Federal only; null for state and council."
               },
               "url": {
                "type": "string",
                "format": "uri",
                "description": "Political Gadgets page for this area."
               }
              }
             },
             "description": "Local government areas (none in the ACT)."
            },
            "federal_next": {
             "type": "array",
             "description": "Boundaries from the NEXT election, only where redrawn (Queensland state; SA, Tasmania and ACT federal). Empty elsewhere.",
             "items": {
              "type": "object",
              "properties": {
               "name": {
                "type": "string"
               },
               "share_percent": {
                "type": "integer"
               }
              }
             }
            },
            "federal_next_note": {
             "type": [
              "string",
              "null"
             ]
            },
            "state_next": {
             "type": "array",
             "description": "Boundaries from the NEXT election, only where redrawn (Queensland state; SA, Tasmania and ACT federal). Empty elsewhere.",
             "items": {
              "type": "object",
              "properties": {
               "name": {
                "type": "string"
               },
               "share_percent": {
                "type": "integer"
               }
              }
             }
            },
            "state_next_note": {
             "type": [
              "string",
              "null"
             ]
            },
            "page": {
             "type": "string",
             "format": "uri"
            },
            "note": {
             "type": "string"
            }
           }
          },
          {
           "type": "object",
           "properties": {
            "ok": {
             "type": "boolean"
            },
            "found": {
             "type": "boolean"
            },
            "message": {
             "type": [
              "string",
              "null"
             ]
            },
            "federal": {
             "type": [
              "string",
              "null"
             ],
             "description": "Federal division name."
            },
            "federal_member": {
             "type": [
              "string",
              "null"
             ]
            },
            "federal_party": {
             "type": [
              "string",
              "null"
             ]
            },
            "federal_pg_url": {
             "type": [
              "string",
              "null"
             ]
            },
            "federal_aec_url": {
             "type": [
              "string",
              "null"
             ]
            },
            "federal_next": {
             "type": [
              "string",
              "null"
             ]
            },
            "federal_next_changed": {
             "type": [
              "boolean",
              "null"
             ]
            },
            "state_code": {
             "type": [
              "string",
              "null"
             ]
            },
            "state_name": {
             "type": [
              "string",
              "null"
             ]
            },
            "state_electorate": {
             "type": [
              "string",
              "null"
             ]
            },
            "state_electorate_url": {
             "type": [
              "string",
              "null"
             ]
            },
            "state_electorate_next": {
             "type": [
              "string",
              "null"
             ],
             "description": "Queensland only: district from the next state election (CC BY-NC 4.0)."
            },
            "lga": {
             "type": [
              "string",
              "null"
             ],
             "description": "Local council area; null in the ACT."
            }
           }
          }
         ]
        }
       }
      }
     }
    }
   }
  },
  "/electorate_finder/geocode.php": {
   "get": {
    "operationId": "geocodeAddress",
    "summary": "Turn an Australian street address into coordinates",
    "description": "Returns candidate matches with lat/lon; pick one, then call lookupElectorates with lat and lon. About one request per 1.5 s per IP (HTTP 429 if faster); do not bulk-geocode.",
    "parameters": [
     {
      "name": "address",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "1 Martin Place Sydney NSW"
     }
    ],
    "responses": {
     "200": {
      "description": "Matches.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "query": {
           "type": "string"
          },
          "matches": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "display_name": {
              "type": "string"
             },
             "lat": {
              "type": "number"
             },
             "lon": {
              "type": "number"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Too many requests."
     }
    }
   }
  }
 }
}