{
  "openapi": "3.1.0",
  "info": {
    "title": "ChargeAlong API",
    "version": "1.0.0",
    "summary": "Public EV charging sites, free and without a key.",
    "description": "Every charging site ChargeAlong lists, with its plugs, power, price, network and position, and the browse hierarchy the site itself is built from.\n\nFree, anonymous and read only. There is no key, no quota and no sign up. Limits at the edge are generous and are there to stop a flood, not to ration use; verified crawlers are not limited at all. Answers are cached for an hour and may be cached by you.\n\nAttribution is a licence condition, not a courtesy: the data comes from Open Charge Map contributors and each record names its own source and licence. Keep those with anything you publish.\n\nFor an agent that speaks MCP, POST https://api.chargealong.io/mcp is the same directory as tools, keyless and stateless: find_chargers, search_places, get_charger and list_networks.\n\nIf you are building on this and want something it does not answer, say so at https://chargealong.io/en/contact/.",
    "contact": {
      "url": "https://chargealong.io/en/contact/"
    },
    "license": {
      "name": "Per record: see each site's sources",
      "url": "https://chargealong.io/en/copyright/"
    }
  },
  "servers": [
    {
      "url": "https://api.chargealong.io",
      "description": "Production"
    }
  ],
  "paths": {
    "/v1/countries": {
      "get": {
        "summary": "Every country with charging sites, and how many each has",
        "responses": {
          "200": {
            "description": "The countries, busiest first"
          },
          "503": {
            "description": "The database is unavailable"
          }
        }
      }
    },
    "/v1/overview": {
      "get": {
        "summary": "What the whole directory holds: countries with their busiest places",
        "responses": {
          "200": {
            "description": "One answer for a home page or a first call"
          },
          "503": {
            "description": "The database is unavailable"
          }
        }
      }
    },
    "/v1/countries/{country}": {
      "get": {
        "summary": "One country: its regions and their counts",
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "description": "Country slug, as in a page URL: australia",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The country and its regions"
          },
          "404": {
            "description": "No such country"
          }
        }
      }
    },
    "/v1/countries/{country}/regions/{region}": {
      "get": {
        "summary": "One region: the places in it that have charging sites",
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "path",
            "required": true,
            "description": "Region slug: victoria",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The region and its localities"
          },
          "404": {
            "description": "No such region"
          }
        }
      }
    },
    "/v1/countries/{country}/networks": {
      "get": {
        "summary": "Every charging network in a country, with its site and region counts",
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The networks, biggest first"
          },
          "404": {
            "description": "No such country"
          }
        }
      }
    },
    "/v1/countries/{country}/networks/{network}": {
      "get": {
        "summary": "One network in a country: where it reaches, and a sample of its sites",
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "network",
            "in": "path",
            "required": true,
            "description": "Network slug: evie-networks",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The network, its regions and its busiest places"
          },
          "404": {
            "description": "No such network in that country"
          }
        }
      }
    },
    "/v1/localities/{country}/{region}/{locality}": {
      "get": {
        "summary": "One suburb or town: every charging site in it, with facet counts",
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locality",
            "in": "path",
            "required": true,
            "description": "Locality slug: sunshine",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The locality, its sites, its facet counts and its neighbours"
          },
          "404": {
            "description": "No such locality"
          }
        }
      }
    },
    "/v1/sites/{publicID}": {
      "get": {
        "summary": "One charging site: connectors, power, price, access, network and position",
        "description": "The public id is the last segment of a site's slug in its page URL, eight characters.",
        "parameters": [
          {
            "name": "publicID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The site, its connectors, its sources and nearby alternatives"
          },
          "404": {
            "description": "No such site"
          },
          "410": {
            "description": "The site was removed from its source"
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Places and sites matching a name",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "At least two characters",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "prefer",
            "in": "query",
            "required": false,
            "description": "Two letter country code, upper case. Places in that country rank first, which is what a search box wants when it knows where the reader is.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching places and sites, best first"
          },
          "400": {
            "description": "The term is too short"
          }
        }
      }
    },
    "/v1/nearby": {
      "get": {
        "summary": "The charging sites nearest a coordinate",
        "description": "Answers the question an answer engine is usually resolving: what is nearest to here, and how fast is it.",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "description": "Latitude in degrees, rounded to four places",
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": true,
            "description": "Longitude in degrees, rounded to four places",
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          },
          {
            "name": "min_kw",
            "in": "query",
            "required": false,
            "description": "Only sites with a connector of at least this many kW. 100 is roughly the line between a stop and a break.",
            "example": 100,
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 400
            }
          },
          {
            "name": "radius_km",
            "in": "query",
            "required": false,
            "description": "How far to look, in kilometres",
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 150,
              "default": 50
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many sites to return, nearest first",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 30
            }
          },
          {
            "name": "connector",
            "in": "query",
            "required": false,
            "description": "Only sites with one of these connectors. Repeat the parameter for more than one.",
            "schema": {
              "type": "string",
              "enum": [
                "ccs2",
                "chademo",
                "type-2",
                "nacs",
                "ccs1",
                "type-1",
                "gbt"
              ]
            }
          },
          {
            "name": "network",
            "in": "query",
            "required": false,
            "description": "Only sites on this network, by slug: evie-networks",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sites near the point, nearest first, with their distance"
          },
          "400": {
            "description": "The coordinates are missing or out of range"
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "summary": "This document",
        "responses": {
          "200": {
            "description": "The OpenAPI description of this API"
          }
        }
      }
    },
    "/v1/redirect": {
      "get": {
        "summary": "Where a page went, if it moved",
        "description": "URLs here are permanent, so this is the exception: a charging site placed in the wrong suburb has its page moved, and its old address answers from this. Ask before treating a 404 as final.",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "description": "A path on this site, starting with a slash: /en/australia/victoria/hampton/ampcharge/x-abcd2345/",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Where it went, and with which status"
          },
          "400": {
            "description": "That is not a path on this site"
          },
          "404": {
            "description": "That path has not moved"
          }
        }
      }
    }
  }
}