{"components":{"parameters":{"dataKey":{"description":"Identifier returned by `/request` (e.g. `20260618aBcDeFgHiJ`)","in":"query","name":"dataKey","required":true,"schema":{"example":"20260618aBcDeFgHiJ","type":"string"}}},"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid request parameters"},"InternalError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"dataKey not found"}},"schemas":{"ErrorResponse":{"properties":{"error":{"example":"Missing required query parameter: dataKey","type":"string"}},"type":"object"},"Icon":{"description":"Custom icon for a map pin. All fields are optional; omitted fields use the default.","properties":{"code":{"description":"FontAwesome Unicode code point as a \\uXXXX escape (e.g. '\\uf276')","example":"\\uf041","type":"string"},"color":{"description":"Icon color as a CSS hex color","example":"#e2041b","type":"string"},"size":{"description":"Icon size in pixels","example":40,"type":"integer"}},"type":"object"},"RequestBody":{"description":"At least one of `center`, `place`, or `markers` is required.","properties":{"center":{"description":"Center coordinates of the map. If omitted and `markers` is provided, the centroid of marker locations is used.","properties":{"lat":{"example":35.6812,"type":"number"},"lng":{"example":139.7671,"type":"number"}},"required":["lat","lng"],"type":"object"},"colorSet":{"description":"Color theme baked into the stored map data. Applied at generation time and used as the default when downloading without specifying `colorSet`. Can be overridden by the `colorSet` query parameter on `GET /download`.","enum":["darkBlue","darkGreen","popArt","lightBlue","lightGreen","beige","magenta","white","gray","black","brawn"],"example":"lightBlue","type":"string"},"icon":{"allOf":[{"$ref":"#/components/schemas/Icon"}],"description":"Custom icon for the `place` pin (or center pin). Omit to use the default."},"layers":{"default":["road","poi"],"description":"Map layers to render (default: `[\"road\", \"poi\"]`).\n\nLayer descriptions:\n- `road` \u2014 All roads including local streets. Supersedes `highway`, `driving`, and `walking`; no need to combine them with `road`\n- `highway` \u2014 Major roads (national/prefectural highways)\n- `driving` \u2014 Roads accessible by car\n- `walking` \u2014 Footpaths and pedestrian walkways\n- `railway` \u2014 Railway lines\n- `waterline` \u2014 Rivers and coastlines\n- `poi` \u2014 Point-of-interest icons (stations, convenience stores, parks, museums, etc.). Filter by type with `poiTypes`","example":["road","railway","poi"],"items":{"enum":["road","highway","driving","walking","railway","waterline","poi"],"type":"string"},"type":"array"},"markers":{"description":"Additional map pins shown in blue. Each marker must have a `label`. If `location` is omitted, it is resolved via geocoding. If neither `center` nor `place` is provided, the centroid of marker locations becomes the center and the radius is set to 1.2\u00d7 the distance from center to the farthest marker.","example":[{"label":"\u6771\u4eac\u99c5"},{"label":"\u9280\u5ea7\u56db\u4e01\u76ee\u4ea4\u5dee\u70b9","location":{"lat":35.6712,"lng":139.7649}}],"items":{"properties":{"icon":{"allOf":[{"$ref":"#/components/schemas/Icon"}],"description":"Custom icon for this marker. Omit to use the default."},"label":{"example":"\u9280\u5ea7\u56db\u4e01\u76ee\u4ea4\u5dee\u70b9","type":"string"},"location":{"description":"Explicit coordinates. Omit to geocode from `label`.","properties":{"lat":{"example":35.6712,"type":"number"},"lng":{"example":139.7649,"type":"number"}},"type":"object"}},"required":["label"],"type":"object"},"type":"array"},"name":{"description":"Map name stored in configDict. Used as the default filename when downloading.","example":"\u6e0b\u8c37\u5468\u8fba","type":"string"},"place":{"description":"Place name; geocoded server-side to set `center`. A red pin is placed at the resolved location.","example":"\u6771\u4eac\u99c5","type":"string"},"poiTypes":{"description":"POI categories to include. Only effective when `layers` contains `poi`. Defaults to all categories.","example":["station","park"],"items":{"enum":["museum","library","theatre","convenience","supermarket","school","religion","station","park","hospital","cityhall","cafe","restaurant"],"type":"string"},"type":"array"},"radius":{"default":500,"description":"Radius from center in meters. Mutually exclusive with `size`. Default: 500","example":500,"maximum":2500,"minimum":1,"type":"integer"},"route":{"description":"Pre-computed route to overlay on the map. Pass the response from `POST /route` directly, or supply `coords` manually. Route segments are drawn on top of all other map layers.","properties":{"color":{"description":"Route line color as a CSS hex string. Omit to use the default route color.","example":"#FF4500","type":"string"},"coords":{"description":"Ordered list of [lat, lng] pairs along the route","example":[[35.672,139.736],[35.671,139.735],[35.668,139.735]],"items":{"items":{"type":"number"},"maxItems":2,"minItems":2,"type":"array"},"type":"array"}},"required":["coords"],"type":"object"},"size":{"description":"Rectangular coverage area in meters. Mutually exclusive with `radius`.","properties":{"ew":{"description":"East-west extent in meters","example":1000,"minimum":1,"type":"number"},"ns":{"description":"North-south extent in meters","example":800,"minimum":1,"type":"number"}},"required":["ew","ns"],"type":"object"},"title":{"description":"Optional title text rendered in the bottom-left corner of the map image.","example":"\u6e0b\u8c37\u30b9\u30af\u30e9\u30f3\u30d6\u30eb\u4ea4\u5dee\u70b9","type":"string"}},"type":"object"},"RouteEndpoint":{"description":"A route start or end point. Provide `location` to use explicit coordinates (no geocoding). Provide only `label` to geocode server-side. Both may be provided \u2014 `location` takes precedence, `label` is used for display.","properties":{"label":{"description":"Place name for geocoding and/or display","example":"\u8d64\u5742\u99c5","type":"string"},"location":{"description":"Explicit coordinates. If provided, geocoding is skipped.","properties":{"lat":{"example":35.6722,"type":"number"},"lng":{"example":139.7364,"type":"number"}},"type":"object"}},"type":"object"},"RouteResponse":{"properties":{"coords":{"description":"Ordered list of [lat, lng] pairs along the computed route","items":{"items":{"type":"number"},"maxItems":2,"minItems":2,"type":"array"},"type":"array"},"from":{"$ref":"#/components/schemas/RouteEndpoint"},"mode":{"enum":["walking","driving"],"type":"string"},"to":{"$ref":"#/components/schemas/RouteEndpoint"}},"type":"object"},"StatusFailed":{"properties":{"dataKey":{"type":"string"},"status":{"enum":["failed"],"type":"string"}},"type":"object"},"StatusPending":{"properties":{"dataKey":{"type":"string"},"status":{"enum":["pending"],"type":"string"}},"type":"object"},"StatusReady":{"properties":{"dataKey":{"type":"string"},"status":{"enum":["ready"],"type":"string"}},"type":"object"}}},"info":{"description":"Asynchronous map image generation API (PNG / SVG) from a place name or coordinates.\n\n## Basic usage\n1. `POST /request` \u2014 enqueue a map generation job; returns a `dataKey`\n2. `GET /status?dataKey=xxx` \u2014 poll until `status: ready`\n3. `GET /download?dataKey=xxx` \u2014 retrieve the generated image\n\n## Notes\n- At least one of `center`, `place`, or `markers` is required\n- `place` geocodes to `center` server-side and places a red pin\n- `markers` adds blue pins; if neither `center` nor `place` is given, the centroid of marker locations is used as center\n- If both `radius` and `size` are given, `radius` takes precedence\n- For `bgColor`, omit the `#` prefix or URL-encode it as `%23` (e.g. `FF0000` or `%23FF0000`)","title":"MapNetwork API","version":"1.0.0"},"openapi":"3.0.0","paths":{"/download":{"get":{"description":"Returns the generated map as PNG or SVG. Returns 202 if still processing, 500 if generation failed (no image in either case).","parameters":[{"$ref":"#/components/parameters/dataKey"},{"description":"Output format (default: png)","in":"query","name":"format","schema":{"default":"png","enum":["png","svg"],"type":"string"}},{"description":"Color theme for the map (default: white)","in":"query","name":"colorSet","schema":{"default":"white","enum":["darkBlue","darkGreen","popArt","lightBlue","lightGreen","beige","magenta","white","gray","black","brawn"],"type":"string"}},{"description":"Background color override. Accepts `RRGGBB` (e.g. `FF0000`), `RGB` (e.g. `F00`), `%23RRGGBB` (URL-encoded `#`), or `transparent`. Applied after `colorSet`.","in":"query","name":"bgColor","schema":{"example":"transparent","type":"string"}},{"description":"Canvas width in pixels (positive integer)","in":"query","name":"canvasWidth","schema":{"example":1000,"minimum":1,"type":"integer"}},{"description":"Canvas height in pixels (positive integer)","in":"query","name":"canvasHeight","schema":{"example":700,"minimum":1,"type":"integer"}},{"description":"Output resolution multiplier (0.01\u20134.0). Cannot be combined with maxWidth/maxHeight.","in":"query","name":"scale","schema":{"maximum":4,"minimum":0.01,"type":"number"}},{"description":"Maximum output width in pixels; image is scaled down if exceeded","in":"query","name":"maxWidth","schema":{"minimum":1,"type":"integer"}},{"description":"Maximum output height in pixels; image is scaled down if exceeded","in":"query","name":"maxHeight","schema":{"minimum":1,"type":"integer"}},{"description":"Road and line width adjustment. Positive values thicken lines, negative values thin them. Default: 0.","in":"query","name":"edgeWeight","schema":{"example":2,"type":"integer"}}],"responses":{"200":{"content":{"image/png":{"schema":{"format":"binary","type":"string"}},"image/svg+xml":{"schema":{"format":"binary","type":"string"}}},"description":"Map image"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPending"}}},"description":"Still processing \u2014 retry after a short delay"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/StatusFailed"},{"properties":{"error":{"type":"string"}},"type":"object"}]}}},"description":"Generation failed or server error"}},"summary":"Download the generated map image"}},"/request":{"post":{"description":"Adds a map generation job to the queue and returns a `dataKey` for tracking. Processing is asynchronous \u2014 poll `/status` until the job is ready.","requestBody":{"content":{"application/json":{"examples":{"coords_with_radius":{"summary":"Coordinates with radius","value":{"center":{"lat":35.6812,"lng":139.7671},"radius":800}},"markers_only":{"summary":"Multiple markers (center auto-derived)","value":{"layers":["road","poi"],"markers":[{"label":"\u6771\u4eac\u99c5"},{"label":"\u9280\u5ea7\u56db\u4e01\u76ee\u4ea4\u5dee\u70b9"}]}},"place_only":{"summary":"Place name only (simplest)","value":{"place":"\u6771\u4eac\u99c5"}},"place_with_poi":{"summary":"Place name with POI filter","value":{"place":"\u6e0b\u8c37\u30b9\u30af\u30e9\u30f3\u30d6\u30eb\u4ea4\u5dee\u70b9","poiTypes":["station","convenience"]}},"rect":{"summary":"Rectangular area","value":{"place":"\u5927\u962a\u57ce","size":{"ew":1200,"ns":900}}}},"schema":{"$ref":"#/components/schemas/RequestBody"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"dataKey":{"example":"20260618aBcDeFgHiJ","type":"string"},"status":{"enum":["queued"],"type":"string"}},"type":"object"}}},"description":"Job accepted and queued"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}},"summary":"Enqueue a map generation job"}},"/route":{"post":{"description":"Resolves from/to locations (geocoding if only a label is given), fetches the street network via osmnx, and returns the shortest-path route as an ordered list of [lat, lng] coordinates.\n\nThe response can be passed directly to the `route` field of `POST /request` to overlay the route on a generated map image.","requestBody":{"content":{"application/json":{"examples":{"place_names":{"summary":"Route between two place names","value":{"from":{"label":"\u8d64\u5742\u99c5"},"mode":"walking","to":{"label":"\u8d64\u5742\u6c37\u5ddd\u795e\u793e"}}},"with_coords":{"summary":"Route with explicit coordinates (skip geocoding)","value":{"from":{"label":"\u51fa\u767a\u5730","location":{"lat":35.6722,"lng":139.7364}},"mode":"walking","to":{"label":"\u76ee\u7684\u5730","location":{"lat":35.6682,"lng":139.7355}}}}},"schema":{"properties":{"from":{"$ref":"#/components/schemas/RouteEndpoint"},"mode":{"default":"walking","description":"Routing mode","enum":["walking","driving"],"type":"string"},"to":{"$ref":"#/components/schemas/RouteEndpoint"}},"required":["from","to"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResponse"}}},"description":"Route computed successfully"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No route found between the two locations"},"500":{"$ref":"#/components/responses/InternalError"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Route computation timed out (retried 4 times)"}},"summary":"Compute a walking/driving route between two locations"}},"/status":{"get":{"description":"Lightweight endpoint for polling job status. Once `status` is `ready`, the image can be retrieved from `/download`.","parameters":[{"$ref":"#/components/parameters/dataKey"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusReady"}}},"description":"Generation complete \u2014 image is ready for download"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPending"}}},"description":"Still processing \u2014 retry after a short delay"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusFailed"}}},"description":"Generation failed"}},"summary":"Check map generation status"}}},"servers":[{"url":"https://mapnetwork.app"}]}