{"openapi":"3.1.0","info":{"title":"hexplace API","version":"1","description":"Town data from open datasets: climate normals by month, housing costs, amenities within a walk, transport access, natural hazards and rankings. No key and no sign-up; CORS is open. Every answer carries its licence and the credit to show, a link to the matching hexplace page.","license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"},"contact":{"name":"hexplace","url":"https://hexplace.org/developers/"}},"externalDocs":{"description":"Developers page","url":"https://hexplace.org/developers/"},"servers":[{"url":"https://hexplace.org/api/v1"}],"security":[],"paths":{"/":{"get":{"operationId":"listCountries","summary":"Countries, their release dates and the endpoints","responses":{"200":{"description":"Countries","content":{"application/json":{"schema":{"allOf":[{"type":"object"},{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/Attribution"}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/{country}/towns":{"get":{"operationId":"listTowns","summary":"Every town with its key values","description":"Values are filled in only where they are precise enough for the town; variables lists each value's label and unit.","parameters":[{"name":"country","in":"path","required":true,"description":"Country slug","schema":{"type":"string","enum":["portugal","spain"]}}],"responses":{"200":{"description":"Towns","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"count":{"type":"integer"},"variables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"unit":{"type":"string"}}}},"towns":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"region":{"type":"string"},"population":{"type":["number","null"]},"url":{"type":"string"},"values":{"type":"object","additionalProperties":{"type":"number"}}}}}}},{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/Attribution"}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/{country}/towns/{slug}":{"get":{"operationId":"getTown","summary":"One town: climate by month, best months, housing, amenities, hazards, who it suits","parameters":[{"name":"country","in":"path","required":true,"description":"Country slug","schema":{"type":"string","enum":["portugal","spain"]}},{"name":"slug","in":"path","required":true,"description":"Town slug, as in the town's page URL (https://hexplace.org/portugal/tavira/)","schema":{"type":"string","example":"tavira"}}],"responses":{"200":{"description":"A town","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"town":{"type":"object"},"summary":{"type":["string","null"]},"climate":{"type":"object"},"housing":{"type":["object","null"]},"within_walk":{"type":"object"},"nearest":{"type":"array"},"hazards":{"type":"object"},"sources":{"type":"array"}}},{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/Attribution"}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/{country}/towns/{slug}/months/{mm}":{"get":{"operationId":"getTownMonth","summary":"One town in one month: highs, lows, rain, sea, crowds, what it is good for","parameters":[{"name":"country","in":"path","required":true,"description":"Country slug","schema":{"type":"string","enum":["portugal","spain"]}},{"name":"slug","in":"path","required":true,"description":"Town slug, as in the town's page URL (https://hexplace.org/portugal/tavira/)","schema":{"type":"string","example":"tavira"}},{"name":"mm","in":"path","required":true,"description":"Month, 01 to 12","schema":{"type":"string","pattern":"^(0[1-9]|1[0-2])$","example":"08"}}],"responses":{"200":{"description":"A town in a month","content":{"application/json":{"schema":{"allOf":[{"type":"object"},{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/Attribution"}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/{country}/rankings":{"get":{"operationId":"listRankings","summary":"The rankings","parameters":[{"name":"country","in":"path","required":true,"description":"Country slug","schema":{"type":"string","enum":["portugal","spain"]}}],"responses":{"200":{"description":"Rankings","content":{"application/json":{"schema":{"allOf":[{"type":"object"},{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/Attribution"}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/{country}/rankings/{id}":{"get":{"operationId":"getRanking","summary":"One ranking, every town in order","parameters":[{"name":"country","in":"path","required":true,"description":"Country slug","schema":{"type":"string","enum":["portugal","spain"]}},{"name":"id","in":"path","required":true,"description":"Ranking id, from /{country}/rankings","schema":{"type":"string","example":"warmest-winters"}}],"responses":{"200":{"description":"A ranking","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"region":{"type":"string"},"value":{"type":"number"},"url":{"type":"string"}}}}}},{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/Attribution"}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/{country}/where/{mm}":{"get":{"operationId":"whereToGo","summary":"The warmest towns in a month","parameters":[{"name":"country","in":"path","required":true,"description":"Country slug","schema":{"type":"string","enum":["portugal","spain"]}},{"name":"mm","in":"path","required":true,"description":"Month, 01 to 12","schema":{"type":"string","pattern":"^(0[1-9]|1[0-2])$","example":"08"}}],"responses":{"200":{"description":"Towns by warmth","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"high_c":{"type":"number"},"low_c":{"type":"number"},"rain_days":{"type":["number","null"]},"sea_c":{"type":["number","null"]},"url":{"type":"string"}}}}}},{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/Attribution"}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Attribution":{"type":"object","description":"The licence and the credit to show with the data","properties":{"licence":{"type":"string"},"licence_url":{"type":"string"},"credit":{"type":"string"},"credit_html":{"type":"string"},"note":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"docs":{"type":"string"}}}}}}