Walking routes

Trick-or-treat route map: what it builds

A family plans a walk, such as a trick-or-treat loop, on your map. Your app shows how many registered addresses are near the walk, draws them as pins without names, and opens the record behind a pin when it is tapped. It shows registered addresses, not where anyone is, and a count is not a rating of the walk.

Draw the walking route

• Let the user draw a line with your map library’s drawing tool (Leaflet.draw, Mapbox GL Draw, the Google Maps drawing tools). Each gives the line as [lng, lat] points.
• A loop that ends where it starts is fine.
• The walk profile takes up to 15 miles and 50 stops. The corridor is 0.1 miles either side by default; up to 0.25.
• Planned stops along the way can be sent as stops, with a radius around each.

Walking route request with the walk profile

// The family draws a loop on your map. Send it, draw nameless pins,
// and open a record only when one is tapped.
const API = 'https://api.offendersearch.app';
const KEY = 'os_map_pk_your_key';  // a map browser key for your site

async function checkWalk(loop, userId) {
  const res = await fetch(API + '/v1/map/route', {
    method: 'POST',
    headers: {
      'X-API-Key': KEY,
      'X-End-User': userId,  // required with a browser key
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      profile: 'walk',
      points: loop,  // [[lng, lat], ...] as drawn
      corridorMiles: 0.1,
      sandbox: true,  // TEST MODE: remove to show real data
    }),
  });
  if (!res.ok) return showError(await res.json());
  const route = await res.json();
  showCount(route.total + ' registered addresses within 0.1 miles of this walk');
  showNotice(route.routeNotice);
  route.markers.forEach((m) => drawPin(m.lat, m.lng, () => openRecord(m.id, userId)));
  route.groups.forEach((g) => drawPin(g.lat, g.lng, () => openGroup(g.groupId), g.count));
}

async function openRecord(markerId, userId) {
  const res = await fetch(API + '/v1/map/records/' + markerId, {
    headers: { 'X-API-Key': KEY, 'X-End-User': userId },
  });
  if (res.ok) showRecord((await res.json()).record);  // one record open
}

Nameless pins on the walking route map

A route answer never carries a name. Draw each marker as a plain dot and each group as a dot with its count. When a dot is tapped, open the record behind it: that is one record open, and opening the same marker again is free.

Draw approximate areas differently, such as a dashed circle labelled “approximate”: those people are known only to a ZIP code, city or county.

Name labels on a walking map: a zoom-15 view

For a map with name labels, request GET /v1/map/viewport for the part of the map on screen at zoom 15 or closer. That is one ordinary map request, with named pins, and it follows the viewport rules. Keep the route answer for the counts along the whole walk.

X-End-User on a walking route app

• A map browser key must send X-End-User with each route call: any stable id for the signed-in person, such as a hashed user id. Without it the call answers 422 end_user_required.
• Each person may check 20 different walks a day by default. Asking about the same walk again does not count.
• Each person may read pins for 2,000 different map squares a day. Counts are never limited by it.
• Send the same X-End-User on the records route, so a daily open limit for each person can apply if you have one.

Walking route app cost

A 2-mile walk with no stops is 2 route units, $0.004. Each record opened is one record open at the account’s rate, $0.035 by default. See Billing.