M Map Snapshot Service

AI Agent API Reference

Use Map Snapshot Service to generate static image/png map snapshots from WGS84 coordinates for reports, documents, notifications, tickets, and README output.

Recipe Chooser

Pick the smallest recipe that matches the report image. The service chooses zoom and image origin automatically.

single-pointOne marker and label for a site, asset, case, or address.
two-pointStart and end markers with separate labels.
multi-pointSeveral markers with supplied labels or automatic numbering.
lineA route, polyline, or measured line with endpoint and segment labels.
polygonAn area boundary such as a work zone, service area, or hazard block.

Shared Request Rules

Rule Value
Method GET and POST are supported. Prefer POST for application integration, long geometry strings, report generation, and generated code. Use GET for short examples and copyable URLs.
Coordinates Use WGS84 lat,lon. Multi-coordinate geometry uses lat,lon;lat,lon;....
Output The response is image/png. When saving files, validate the content type or PNG signature before embedding in a report.
Size Suggested report default is 416 x 416. width is clamped from 320 to 1024; height is clamped from 240 to 1024; padding defaults to 40.

Basemap Guidance

Key Use
osm Recommended default for general report images.
emap5 Recommended for Taiwan government-style map output.
google, google-satellite, google-terrain Available for demo and compatibility use. Do not make these the default for production integrations without reviewing provider policy.

Callers cannot provide custom tile URLs. The renderer uses a provider allowlist to avoid turning the service into a generic HTTP proxy.

Endpoint Reference

Single Point Snapshot

POST /api/single-point.php

Required: latLon. Optional: name, basemap, width, height, padding.

curl -X POST 'https://3wa.tw/demo/php/map/map-snapshot-service/api/single-point.php' \
  --data-urlencode 'latLon=24.1782252,120.6484168' \
  --data-urlencode 'name=逢甲大學' \
  --data-urlencode 'basemap=osm' \
  --data-urlencode 'width=416' \
  --data-urlencode 'height=416' \
  --output single-point.png

Two Point Snapshot

POST /api/two-point.php

Required: sLatLon, eLatLon. Optional: sName, eName, basemap, width, height, padding.

curl -X POST 'https://3wa.tw/demo/php/map/map-snapshot-service/api/two-point.php' \
  --data-urlencode 'sLatLon=24.1782252,120.6484168' \
  --data-urlencode 'eLatLon=24.1111272,120.6100528' \
  --data-urlencode 'sName=起點: 逢甲大學' \
  --data-urlencode 'eName=目的地: ICC 辦公大樓' \
  --data-urlencode 'basemap=osm' \
  --data-urlencode 'width=416' \
  --data-urlencode 'height=416' \
  --output two-point.png

Multi Point Snapshot

POST /api/multi-point.php

Required: points with at least two coordinates. Optional: names or labels, basemap, width, height, padding.

curl -X POST 'https://3wa.tw/demo/php/map/map-snapshot-service/api/multi-point.php' \
  --data-urlencode 'points=24.1782252,120.6484168;24.1111272,120.6100528;24.1700000,120.6500000' \
  --data-urlencode 'names=逢甲大學;ICC 辦公大樓;水湳測試點' \
  --data-urlencode 'basemap=osm' \
  --data-urlencode 'width=416' \
  --data-urlencode 'height=416' \
  --output multi-point.png

Line Snapshot

POST /api/line.php

Required: points with at least two coordinates, or legacy sLatLon and eLatLon. Optional: sName, eName, lineNames, basemap, width, height, padding.

curl -X POST 'https://3wa.tw/demo/php/map/map-snapshot-service/api/line.php' \
  --data-urlencode 'points=24.1782252,120.6484168;24.1600000,120.6400000;24.1450000,120.6280000;24.1280000,120.6200000;24.1111272,120.6100528' \
  --data-urlencode 'sName=逢甲大學' \
  --data-urlencode 'eName=ICC 辦公大樓' \
  --data-urlencode 'lineNames=5km,2km,,200m' \
  --data-urlencode 'basemap=osm' \
  --data-urlencode 'width=416' \
  --data-urlencode 'height=416' \
  --output line.png

Polygon Snapshot

POST /api/polygon.php

Required: points with at least three coordinates. Optional: name, basemap, width, height, padding. Empty or omitted name draws no label bubble.

curl -X POST 'https://3wa.tw/demo/php/map/map-snapshot-service/api/polygon.php' \
  --data-urlencode 'points=24.1835000,120.6422000;24.1835000,120.6578000;24.1722000,120.6578000;24.1722000,120.6422000' \
  --data-urlencode 'name=逢甲周邊範圍' \
  --data-urlencode 'basemap=osm' \
  --data-urlencode 'width=416' \
  --data-urlencode 'height=416' \
  --output polygon.png

Report Integration Checklist

  1. Choose the recipe that matches the report map: point, pair, point set, line, or polygon.
  2. Normalize source coordinates to WGS84 lat,lon.
  3. Build POST form data with labels, basemap, width, and height.
  4. Call the endpoint and confirm HTTP success.
  5. Confirm response Content-Type is image/png or the first eight bytes match the PNG signature.
  6. Save the image into the report output directory.
  7. Embed the saved relative path or public URL in the report.

Agent Safety Rules

  • Do not bulk-render many uncached maps against the public demo.
  • Do not send sensitive coordinates to the public demo unless that is acceptable for the system.
  • Do not assume custom tile URLs are supported.
  • Do not scrape cache files directly.
  • Do not remove provider attribution from generated PNGs.
  • Prefer fixture basemaps or a local/test service for automated tests.

Minimal Integration Snippet

This pseudo-code is intentionally generic so agents can translate it into PHP, Python, C#, Node.js, or a report-generation job.

response = http.post(
  base_url + "api/single-point.php",
  form={
    "latLon": "24.1782252,120.6484168",
    "name": "逢甲大學",
    "basemap": "osm",
    "width": "416",
    "height": "416"
  }
)

assert response.status_code == 200
assert response.headers["content-type"].starts_with("image/png")
assert response.bytes[0:8] == b"\x89PNG\r\n\x1a\n"

write_file("report-output/map-single-point.png", response.bytes)
embed_image("report-output/map-single-point.png")