Static maps

One address gives a picture of the map: put it in an <img>, an email, a PDF receipt or a WhatsApp message. N-Ways draws it on its own servers from the same map as the Maps SDK.

Make one

<img
  width="600" height="300" alt="Map of the delivery address"
  src="https://nways.ng/maps/v1/staticmap?center=6.6018,3.3515&zoom=15&size=600x300&scale=2&markers=color:green|6.6018,3.3515&key=YOUR_API_KEY" />

The picture carries the OpenStreetMap credit in its corner: don’t crop it out. Each picture is one static map call for billing; the same address asked again soon is served from cache.

From JavaScript

import { staticMapUrl } from '@nways/maps'

img.src = staticMapUrl({
  key: 'YOUR_API_KEY',
  size: [600, 300],
  scale: 2,
  markers: [
    { at: { lat: 6.5965, lng: 3.3421 }, color: 'orange', label: 'P' },
    { at: { lat: 6.6018, lng: 3.3515 }, color: 'green', label: 'D' },
  ],
  path: { points: routes[0].geometry.coordinates, color: '#1e6fe8', weight: 5 },
})

Long routes make long addresses: keep a URL under about 8,000 characters by thinning the line’s points, or use an encoded polyline.

Signed URLs

A key restricted to your website only works where the browser says the request comes from your site. Emails, receipts and messages don’t, so sign those addresses on your server: the signature proves the address came from you, and it then works anywhere, still within the key’s API restrictions, limits and credit.

1. Copy the key’s URL signing secret from its card in the partner console (your organisation’s owners and developers can see it). Keep it on your server only. Rotating it, or regenerating the key, makes every older signature stop working.
2. Build the address with the key, then sign its path and query: HMAC-SHA256 with the secret (base64url-decoded), over the text from /maps/v1/staticmap? to the end.
3. Add &signature= and the result in base64url, last.

import { createHmac } from 'node:crypto'

function signed(url, secret) {
  const u = new URL(url)
  const sig = createHmac('sha256', Buffer.from(secret, 'base64url')).update(u.pathname + u.search).digest('base64url')
  return `${url}&signature=${sig}`
}

const url = signed('https://nways.ng/maps/v1/staticmap?center=6.6018,3.3515&zoom=15&size=600x300&key=YOUR_API_KEY', process.env.NWAYS_SIGNING_SECRET)

import base64
import hashlib
import hmac
import os
from urllib.parse import urlsplit


def signed(url: str, secret: str) -> str:
    u = urlsplit(url)
    key = base64.urlsafe_b64decode(secret + "=" * (-len(secret) % 4))
    digest = hmac.new(key, f"{u.path}?{u.query}".encode(), hashlib.sha256).digest()
    return url + "&signature=" + base64.urlsafe_b64encode(digest).decode().rstrip("=")


url = signed("https://nways.ng/maps/v1/staticmap?center=6.6018,3.3515&zoom=15&size=600x300&key=YOUR_API_KEY", os.environ["NWAYS_SIGNING_SECRET"])

A wrong signature is refused (403). Never sign addresses in a web page: the secret would be in the page.