{"openapi":"3.1.0","info":{"title":"Walletmix Map API","version":"1.0.0","summary":"Self-Hosted Bangladesh Mapping, Geocoding, Places, Routing, Matrix & Vector Tile API","description":"Commercial developer API for Walletmix Map (https://map.walletmix.com). All coordinates strictly follow [longitude, latitude] order in WGS84 (EPSG:4326). Powered by self-hosted OpenStreetMap Bangladesh data, Planetiler/OpenMapTiles vector tiles, Nominatim, PostGIS, and OSRM.","license":{"name":"ODbL 1.0 (Map Data) / Walletmix Commercial API Terms","url":"https://www.openstreetmap.org/copyright"},"contact":{"name":"Walletmix Limited","url":"https://map.walletmix.com/developers"}},"servers":[{"url":"https://map.walletmix.com/api/v1","description":"Production Bangladesh Server (KVM-8)"}],"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Walletmix Map Browser (wmap_pub_live_...) or Server (wmap_sec_live_...) API Key"},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"API key passed via query parameter (recommended for MapLibre style/tile URLs)"}}},"paths":{"/geocode":{"get":{"summary":"Forward Geocode Bangladesh Address or Place","operationId":"geocode","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200},"description":"Search query in English or Bangla (e.g., \"Uttara Sector 7\" or \"উত্তরা\")"},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["en","bn"],"default":"en"}},{"name":"district","in":"query","required":false,"schema":{"type":"string"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":1}}],"responses":{"200":{"description":"Geocoding results with [longitude, latitude] coordinates and ODbL attribution"},"400":{"description":"Validation error"},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit or daily quota exceeded"}}}},"/reverse":{"get":{"summary":"Reverse Geocode [longitude, latitude] Coordinates","operationId":"reverseGeocode","parameters":[{"name":"lon","in":"query","required":true,"schema":{"type":"number","example":90.3984},"description":"Longitude in WGS84 (~88.0 to 92.7 for Bangladesh)"},{"name":"lat","in":"query","required":true,"schema":{"type":"number","example":23.8759},"description":"Latitude in WGS84 (~18.5 to 26.6 for Bangladesh)"},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["en","bn"],"default":"en"}}],"responses":{"200":{"description":"Structured address and nearby landmarks"},"400":{"description":"Invalid or swapped coordinates, or outside Bangladesh coverage"}}}},"/autocomplete":{"get":{"summary":"Bilingual (English & Bangla) Place Autocomplete","operationId":"autocomplete","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["en","bn"],"default":"en"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":8}},{"name":"focus_lon","in":"query","required":false,"schema":{"type":"number"}},{"name":"focus_lat","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Autocomplete suggestions with [lon, lat] coordinates"}}}},"/places/nearby":{"get":{"summary":"Find Nearby Places Within Radius","operationId":"placesNearby","parameters":[{"name":"lon","in":"query","required":true,"schema":{"type":"number","example":90.3984}},{"name":"lat","in":"query","required":true,"schema":{"type":"number","example":23.8759}},{"name":"radius_m","in":"query","required":false,"schema":{"type":"number","minimum":10,"maximum":25000,"default":1500}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Places sorted by distance in meters"}}}},"/places/{id}":{"get":{"summary":"Get Place Details by ID","operationId":"getPlaceById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"osm_landmark_uttara_center"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["en","bn"],"default":"en"}}],"responses":{"200":{"description":"Detailed place record with ODbL provenance"},"404":{"description":"Place not found"}}}},"/route":{"post":{"summary":"Calculate Driving Route (Self-Hosted OSRM)","operationId":"calculateRoute","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"example":[90.3984,23.8759]},"destination":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"example":[90.4178,23.733]},"waypoints":{"type":"array","items":{"type":"array","items":{"type":"number"}}},"profile":{"type":"string","enum":["driving"],"default":"driving"},"steps":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Driving route geometry (GeoJSON LineString), distance, baseline duration, and turn-by-turn steps"},"400":{"description":"Unsupported travel mode, invalid coordinates, or >25 waypoints"}}}},"/matrix":{"post":{"summary":"Calculate Road Distance & Duration Matrix (Max 100 Elements)","operationId":"calculateMatrix","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["origins","destinations"],"properties":{"origins":{"type":"array","items":{"type":"array","items":{"type":"number"}},"example":[[90.3984,23.8759],[90.4146,23.7947]]},"destinations":{"type":"array","items":{"type":"array","items":{"type":"number"}},"example":[[90.4178,23.733],[90.3742,23.7465]]},"profile":{"type":"string","enum":["driving"],"default":"driving"}}}}}},"responses":{"200":{"description":"2D arrays of distances_meters and durations_seconds"},"400":{"description":"Matrix dimensions exceed 25x25 or 100 total elements"}}}},"/styles/{style}":{"get":{"summary":"Get MapLibre GL Style Specification (walletmix-light.json or walletmix-dark.json)","operationId":"getMapStyle","parameters":[{"name":"style","in":"path","required":true,"schema":{"type":"string","enum":["walletmix-light.json","walletmix-dark.json"]}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["en","bn","bilingual"],"default":"bilingual"}}],"responses":{"200":{"description":"MapLibre Style JSON v8 pointing to self-hosted tiles, glyphs, and sprites"}}}},"/health":{"get":{"summary":"Platform & Backing Services Health Check","operationId":"getHealth","security":[],"responses":{"200":{"description":"All backing services (PostGIS, Redis, TileServer, OSRM, Nominatim) healthy"}}}}},"x-coverage":{"region":"Bangladesh (Nationwide — 8 Divisions, 64 Districts)","iso_country":"BD","bbox_lon_lat":[87.99765,18.58403,92.697142,26.64677],"dataset_version":"v20261024","dataset_timestamp":"2026-10-24T20:20:51Z","replication_sequence":4918,"data_source":"Geofabrik Bangladesh Extract (OpenStreetMap)","supported_travel_modes":["driving"],"unsupported_travel_modes":["walking","cycling","transit","live_traffic"],"unavailable_features":["satellite_imagery","street_view","live_traffic_predictions","voice_navigation"]},"x-attribution":{"text":"© Walletmix Map | Map data © OpenStreetMap contributors (ODbL 1.0) | Tiles © OpenMapTiles (CC-BY 4.0)","text_bn":"© ওয়ালেটমিক্স ম্যাপ | মানচিত্রের তথ্য © OpenStreetMap অবদানকারীগণ (ODbL 1.0)","license":"ODbL-1.0","tiles_license":"CC-BY-4.0","osm_copyright_url":"https://www.openstreetmap.org/copyright","odbl_url":"https://opendatacommons.org/licenses/odbl/1-0/","provenance_notice":"OpenStreetMap data is licensed under the Open Data Commons Open Database License (ODbL 1.0). Independently collected records combined with OSM-derived geocoding or spatial databases may trigger collective or derivative database obligations under ODbL."}}