MapWise API

Quick Start

1. Get a secret key. Open My Account → MapWise API and choose Generate new secret key. Copy the key straight away: it is shown once. Authentication covers who can create keys and how to store and send them.
2. Make a first request. From a terminal or your server, run a small search:

   curl "https://www.mapwise.com/api_v2/parcels?searchCounty=ALACHUA&limit=1" \
     -H "X-API-Key: YOUR_API_KEY"

   Replace YOUR_API_KEY with your key. Searches are billed per record returned, at the rate in Data & Pricing. To see the response format first, with no key and no charge, send the same query to /parcels/test, which answers with masked Alachua County records.
3. Check the response. Success is HTTP 200 with "success": true, the matching parcels in data, and how many came back in meta.record_count. The full response is shown under Search parcels. A 401 means the key was missing or wrong; every other failure is listed in Error Responses.
4. Where to go next. See Parcels for every search parameter, Rate Limiting and Monthly Spend Caps for the limits on your key, and Rotating a Key before you deploy.

Authentication

There are two kinds of key, and they are not interchangeable.

Both keys bill to your account. MapWise Pro includes API access, but usage is metered, not included: everything either key reads or draws is charged at the rates below. The difference between the two keys is reach, not cost. A secret key can read every product you pay for, from anywhere, while a publishable key can only draw tiles, and only from the sites you listed. Keep that list tight and watch your usage on Usage & spend.

Managing secret keys

A secret key starts with mw_sk_. Keys issued before that format are 64 hex characters and keep working unchanged. In My Account they show a bare last four characters, and the oldest, made before any of the key was recorded for display, are listed as Legacy key.

Who can create keys. Keys come with a paid MapWise Pro subscription that has a payment method on file; on a free trial, you can create one once the trial converts to paid. Creating, renaming and revoking keys needs the Super Admin or Billing role. When a request is refused, the dashboard shows why; the reasons are listed under Error Responses.

• Shown once. The full key appears only when you create it. MapWise stores a hash, not the key, so it cannot show it again: afterwards the list shows its label and, for an mw_sk_ key, its last four characters. If you lose a key, create a new one and revoke the old.
• Several keys. Each user can hold up to 10 live secret keys at a time. Give each integration its own key, with a label saying where it runs, so revoking one does not break the others. Labels can be renamed; the key itself does not change. At the limit, creating another is refused with LIMIT_REACHED: revoke one you no longer use.
• Revoking. Revoke a key from the same list. It stops working on the next request, answering 401, and cannot be restored. You can revoke your last key and create another later.
• Security email. Whenever a key, secret or publishable, is created or revoked, MapWise sends a security email to the key’s owner and to every other user on the account who can manage keys. It names the key, who acted and when. It cannot be turned off. It is best-effort: if it cannot be sent, the key action still succeeds, so the list in My Account remains the record of your keys. If you did not expect one, revoke the key and contact us.

Rotating a key

There is no rotate button. You rotate by running two keys side by side for a moment, so no request fails in between:

1. Create a new secret key and store it wherever your integration reads its secrets.
2. Switch your integration to the new key, and confirm its requests succeed.
3. Revoke the old key in My Account.

Rotate when someone who had the key leaves, when it may have been exposed, or on the schedule your own security policy sets. If a key has leaked, revoke it first rather than waiting for the switch.

Sending a key

Send a secret key on every data request to https://www.mapwise.com/api_v2, either way:

• X-API-Key: YOUR_API_KEY
• Authorization: Bearer YOUR_API_KEY

Keep a secret key on your server, in an environment variable or a secrets manager. Never put it in a browser page, a mobile app or a repository: anything shipped to a device can be read by its user, and a key committed to a repository stays in its history after you delete the file. Do not put it in a URL either, where it ends up in logs.

Sending the wrong class is refused rather than downgraded: the response is 403 with KEY_CLASS_MISMATCH. A publishable key cannot read data, and a secret key is not accepted from a browser.

A publishable key goes in the query string instead, as ?apiKey=mw_pk_…, from a page on one of the websites you registered. Map libraries send it that way for you; see Map Tiles. Never send it in a header: a browser will not send X-API-Key to another site.

Create either kind in My Account → MapWise API.

Data & Pricing

API access is included with MapWise Pro. There is no separate API plan. You pay for what you use, billed monthly:

These are standard rates. Your account’s own rates, including any negotiated price, are shown under Usage & spend in My Account. For volume pricing, contact us.

• County coverage: all 67 Florida counties with complete sales history and property records.
• Data updates: weekly to biweekly from official county property appraiser sources (statewide median under a week).
• Test endpoint: free. Requests to /parcels/test do not count toward billing.

Monthly Spend Caps

Every account includes a monthly spend cap, $100/month by default. Adjust it from My Account → MapWise API → Monthly Spend Cap (requires the Super Admin or Billing role), up to the account maximum of $1,000/month; for higher limits, contact us about enterprise pricing. Once the cap is reached, further billable requests are declined with 429 until usage resets on the 1st of the month (00:00 UTC). Email warnings send at 50%, 80%, and 100% of the cap.

Security note: a leaked key cannot raise its own cap. Spend-cap changes require an authenticated dashboard session, not the API key.

Every billable response includes your current spend state in headers:

X-Billing-Period-Spend-Cents: 1200
X-Billing-Period-Cap-Cents: 3000
X-Billing-Period-Reset: 2026-08-01T00:00:00Z

A cap-exceeded response is a 429, like a rate limit, but not the envelope every other failure uses. It is its own shape, with no errormsg to read. Check for a top-level error to tell the two apart:

{
  "error": "spend_cap_exceeded",
  "endpoint": "parcels",
  "current_spend_cents": 10000,
  "cap_cents": 10000,
  "reset_at": "2026-10-01T00:00:00Z",
  "estimated_call_cost_cents": 6,
  "request_id": "01a0ba0a-e8f4-7fff-853c-bbce832d6c46"
}

It carries Retry-After set to the period reset, which may be days away, so treat it differently from a rate limit: backing off will not help before reset_at. Either raise the cap in My Account or wait for the reset. current_spend_cents against cap_cents tells you which.

Rate Limiting & Security

Each endpoint draws on one of two kinds of bucket, and the table shows which:

• account is one budget shared across all the keys on your account. It refills at the sustained rate and allows a burst: you can spend up to the burst at once, for a run of parallel lookups, after which you are held to the sustained rate.
• endpoint is a separate budget for that one endpoint, so a busy endpoint cannot use up what another needs. Map tiles have their own, because a single pan or zoom fetches dozens of tiles.

Every response tells you where you stand, so a client can pace itself rather than guess:

Over the limit is a 429 with a Retry-After header saying when to come back. A 429 can also mean your monthly spend cap is reached rather than your rate limit. The body’s error field says which, and spend_cap_exceeded means waiting will not help until the period resets. Back off exponentially either way; do not retry in a tight loop.

Need more throughput? Contact us. These are defaults, not ceilings.

Security best practices:

• Store API keys in environment variables. Never commit them to version control.
• Use HTTPS for all requests.
• Monitor your API usage and rate limits.

MapWise aerial imagery as standard XYZ raster tiles, which every mainstream map library draws, including MapLibre GL JS, Leaflet and OpenLayers. Each tileset also has a TileJSON document, which MapLibre and OpenLayers read natively. Six Florida tilesets, zoom 4 to 21, drawn straight from your own web page. Every tile is a 256 px JPEG.

1. Get a publishable key and register your websites

Tiles take a publishable key (mw_pk_…) and nothing else; a secret key is refused. Create one under My Account → MapWise API and list the websites that will show the map (https://your-site.example, plus http://localhost:5173 while you develop). The key is origin-locked: it is safe in a web page, and browsers on other websites are refused. Outside a browser an Origin header can be forged, so treat the lock as the first line of defence, not the only one. You are responsible for every request made with your key; your monthly spend cap bounds what a misused key can cost, and you can revoke a key and create a new one at any time.

A registered host covers its subdomains, but the scheme and the port must match exactly. A key registered for http://localhost:5173 is refused on https://localhost:5173 and on http://localhost:5174 alike, so register each port you develop on.

Because subdomains are included, register the site you own, not a shared hosting domain above it. If your demo lives at https://your-team.github.io, register that, never https://github.io: the parent would let every site on that host draw tiles on your key. The same goes for netlify.app, vercel.app, pages.dev and similar hosts.

Send the key as the apiKey query parameter, the way every tile client expects. X-API-Key is not usable from a web page, since a browser's CORS preflight will not allow that header from another site, and the terms license tiles for display in browser pages only.

2. Add the source to your map

The tile template is the universal path: any library can draw https://www.mapwise.com/api_v2/tiles/{tileset}/{z}/{x}/{y}.jpg?apiKey=… directly. The TileJSON document is offered because it carries minzoom, maxzoom, bounds and attribution for you, and its tiles[] template already has your key in it: no request interception, no headers. MapLibre and OpenLayers read it natively; Leaflet has no TileJSON loader, so its sample uses the template.

Keep the attribution visible. Show it on the map or immediately next to it, and do not remove it or let your interface cover it. A corner of the map (lower-right is conventional) is the usual place; check it stays legible against the imagery, which is brighter and busier than most basemaps.

Each tileset's TileJSON carries the string, and the libraries that read the document display it for you. For aerials-latest it is Imagery: FDOT / FDOR / Florida counties · Tiles © MapWise, with each source linked.

MapLibre, Leaflet and OpenLayers render it as HTML. The TileJSON spec also permits a client to treat the field as plain text, so handle the markup if you render it yourself.

Our tiles are 256 px. MapLibre's raster default is 512, so set tileSize: 256 there or the imagery draws at the wrong scale.

const map = new maplibregl.Map({
  container: 'map',
  style: { version: 8, sources: {}, layers: [] },
  center: [-81.38, 28.54],
  zoom: 12,
});

map.on('load', () => {
  map.addSource('mapwise-aerials', {
    type: 'raster',
    url: 'https://www.mapwise.com/api_v2/tiles/aerials-latest/tiles.json?apiKey=mw_pk_YOUR_PUBLISHABLE_KEY',
    tileSize: 256,   // our tiles are 256 px; MapLibre's raster default is 512
  });
  map.addLayer({ id: 'aerials', type: 'raster', source: 'mapwise-aerials' });
});

// Attribution is required. MapLibre reads it from the TileJSON and shows it
// in the attribution control:
// Imagery: <a href="https://www.fdot.gov/">FDOT</a> / <a href="https://floridarevenue.com/">FDOR</a> / Florida counties · Tiles © <a href="https://www.mapwise.com/">MapWise</a>

const map = L.map('map').setView([28.54, -81.38], 12);

// Leaflet has no TileJSON loader, so the tile template goes in directly.
// minZoom/maxZoom and bounds keep it from asking for tiles that do not
// exist. Every request is billed, including a blank one.
L.tileLayer('https://www.mapwise.com/api_v2/tiles/aerials-latest/{z}/{x}/{y}.jpg?apiKey=mw_pk_YOUR_PUBLISHABLE_KEY', {
  tileSize: 256,
  minZoom: 4,
  maxZoom: 21,
  bounds: L.latLngBounds([24.5, -87.6], [31.2, -80.0]),
  attribution: 'Imagery: <a href="https://www.fdot.gov/">FDOT</a> / <a href="https://floridarevenue.com/">FDOR</a> / Florida counties · Tiles © <a href="https://www.mapwise.com/">MapWise</a>',   // required
}).addTo(map);

const layer = new ol.layer.Tile({
  source: new ol.source.TileJSON({
    url: 'https://www.mapwise.com/api_v2/tiles/aerials-latest/tiles.json?apiKey=mw_pk_YOUR_PUBLISHABLE_KEY',
    crossOrigin: 'anonymous',   // tiles and tiles.json both send Access-Control-Allow-Origin: *
  }),
});

new ol.Map({
  target: 'map',
  layers: [layer],
  view: new ol.View({ center: ol.proj.fromLonLat([-81.38, 28.54]), zoom: 12 }),
});

// Attribution is required. OpenLayers takes it from the TileJSON:
// Imagery: <a href="https://www.fdot.gov/">FDOT</a> / <a href="https://floridarevenue.com/">FDOR</a> / Florida counties · Tiles © <a href="https://www.mapwise.com/">MapWise</a>

To read the zoom range and footprint from the document rather than pasting them, in Leaflet: fetch(tileJsonUrl).then((r) => r.json()).then((tj) => L.tileLayer(tj.tiles[0], { minZoom: tj.minzoom, maxZoom: tj.maxzoom, attribution: tj.attribution }).addTo(map)).catch(console.error). It costs one extra request, and the attribution comes with it.

Tilesets

All six cover Florida and run from zoom 4 to 21. GET /tiles lists exactly the tilesets your own key can fetch, each with its tile template and TileJSON path.

Aerials — Latest aerials-latest

Imagery: most recent available per county · FDOT / FDOR / Florida counties. TileJSON: https://www.mapwise.com/api_v2/tiles/aerials-latest/tiles.json

Aerials — NAIP Latest aerials-naip-latest

NAIP latest · USDA NAIP. TileJSON: https://www.mapwise.com/api_v2/tiles/aerials-naip-latest/tiles.json

Aerials — 2023 CIR aerials-naip-2023-cir

NAIP 2023 CIR · USDA NAIP, colour-infrared. TileJSON: https://www.mapwise.com/api_v2/tiles/aerials-naip-2023-cir/tiles.json

Aerials — 2004 DOQ aerials-doq2004

2004 digital orthophoto quads · FDOT / FDOR. TileJSON: https://www.mapwise.com/api_v2/tiles/aerials-doq2004/tiles.json

Aerials — 1999 CIR aerials-doq1999

1999 digital orthophoto quads, colour-infrared · USGS. TileJSON: https://www.mapwise.com/api_v2/tiles/aerials-doq1999/tiles.json

Aerials — 1995 CIR aerials-doq1995

1995 digital orthophoto quads, colour-infrared · USGS. TileJSON: https://www.mapwise.com/api_v2/tiles/aerials-doq1995/tiles.json

Billing and caching

• $0.50 / 1,000 tiles, flat. Every tile request that reaches the API counts. Usage is summed per calendar month and rounded up to the next 1,000 tiles when the month closes, so the smallest monthly tile charge is one block at that rate. There is no free allowance at launch.
• A tile served from cache while it is still fresh never reaches the API, and is never billed. That is the one thing that lowers your bill, so let tiles cache: do not disable the browser cache, do not append cache-busting parameters, and do not serve them through a proxy, CDN, or other shared cache.
• A revalidation is a billed request. Every tile carries an ETag, and a Last-Modified where the imagery backend publishes one. When a cached tile's lifetime has elapsed your client asks whether it is still current, and that question reaches the API, so it counts, even when the answer is 304 Not Modified and no image comes back. Revalidation saves you bandwidth and time, not money. The only way to spend less is to not send the request.
• Cache lifetimes: 24 hours on the rolling imagery (aerials-latest, aerials-naip-latest) and 30 days, marked immutable, on the dated vintages. A dated vintage never changes, so a well-behaved client should serve it from cache until it expires and not revalidate it at all.
• A blank tile outside the imagery footprint bills like any other, as does a tile at a zoom with no imagery. bounds, minzoom and maxzoom let your client skip those before it asks; libraries that read the TileJSON do it automatically.
• What does not bill: a request refused before any imagery is fetched. That covers 403 (a site the key does not list, or the wrong key class), 404 (unknown tileset), 402 (monthly spend cap reached) and 502 (the imagery backend failed).
• Tile requests are capped. The tile image route accepts 60 tiles per second, 600 tiles per minute, 100,000 tiles per day. Past a cap you get a 429 with a Retry-After header; see Rate Limiting.
• Your monthly spend cap is the ceiling. Per-tile spend is hard to forecast from a map's behaviour, so the cap, not a rate sheet, is what makes it predictable: it is $100 by default and you set it under My Account → MapWise API. Tile requests are declined once it is reached.

Error Responses

Every failure has the same shape:

{
  "success": false,
  "status": 400,
  "timestamp": "2026-09-20 15:56:09.032819",
  "errormsg": "Query validation failed.",
  "errors": [
    "Parameter 'limit' has an invalid format (received 'abc').",
    "Missing required parameter: searchCounty"
  ],
  "help": { "message": "For a complete list of valid parameters..." }
}

A 400 carries an errors array with one entry per failed rule and a help object pointing at the parameters involved. Other failures carry the same four fields with no errors.

Where a refusal has a machine-readable reason, branch on that rather than on errormsg, whose wording is written for a person and can change. A request a key gate refused carries it at data.code (KEY_CLASS_MISMATCH when a key of the wrong class is used), and a path that does not route carries it at the top level.

Every response carries an X-Request-Id, including failures. It identifies that one request in our logs, so include it when you contact us and we can find what happened instead of searching. Send your own if you would rather correlate with your logs: up to 64 letters, digits and hyphens, and we will use yours instead of ours, so send something unique per request.

Refusals when creating a key

These come from My Account rather than from a data request, and the dashboard shows their message. Each is a 403, and all but the first carry the code shown:

Best Practices

• Validate all user-supplied input before sending requests.
• Check meta.record_count to determine if any results were returned.
• Handle non-200 HTTP status codes gracefully in your application.
• Implement exponential backoff when you receive a 429 response.
• All error responses include success: false and an errormsg field.
• Give each integration its own secret key, and rotate it with the rotation steps, which overlap the old and new keys so nothing fails in between.

Contact & Support

Questions about the API, higher rate limits, or enterprise pricing? Contact us.