MapWise API

Quick start

1. Get a secret key. Open My Account > MapWise API and choose Generate new secret key. Copy the key right away, because 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 and pricing. To see the response format first, send the same query to /parcels/test. It needs no key, costs nothing and answers with masked Alachua County records.
3. Check the response. Success is HTTP 200 with "success": true. The matching parcels are in data, and meta.record_count says how many came back. See Search parcels for the full response. A 401 means the key was missing or wrong. See Error responses for every other failure.
4. Where to go next. See Parcels for every search parameter. See Rate limiting and Monthly spend caps for the limits on your key. Read Rotate 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 and $20 of API usage each month. Everything above that, read or drawn by either key, is charged at the rates below. The two keys differ in reach, not cost. A secret key can read every product you pay for, from anywhere. A publishable key can only draw tiles, and only from the sites you listed. Keep that list short, and watch your usage on Usage & spend.

Manage 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, these older keys show their last four characters with no prefix. The oldest were made before MapWise recorded any part of a key for display, and are listed as Legacy key.

Who can create keys. Keys need a paid MapWise Pro subscription with a payment method on file. On a free trial, you can create a key once the trial converts to paid. Creating, renaming and revoking keys needs the Super Admin or Billing role. If the API refuses a request, 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 the key again. After that, the list shows the key’s label and, for an mw_sk_ key, its last four characters. If you lose a key, create a new one and revoke the old one.
• 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. You can rename a label; the key itself does not change. At the limit, MapWise refuses a new key with LIMIT_REACHED. Revoke one you no longer use.
• Revoking. Revoke a key from the same list. It stops working on the next request, which gets a 401. You cannot restore it. You can revoke your last key and create another later.
• Security email. When a key, secret or publishable, is created or revoked, MapWise sends a security email. It goes 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. You cannot turn it off. Delivery is best-effort. If the email cannot be sent, the key action still succeeds, so treat the list in My Account as the record of your keys. If you did not expect an email, revoke the key and contact us.

Rotate a key

To rotate a key, run the old and new keys side by side for a moment, so no request fails in between. There is no rotate button.

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

Rotate a key when someone who had it leaves, when it may have been exposed, or on your own security policy’s schedule. If a key has leaked, revoke it before you create its replacement. Do not wait for the switch.

Send a key

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

• 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. The user of a device can read anything shipped to it. A key committed to a repository stays in its history after you delete the file. Do not put the key in a URL either, because URLs end up in logs.

If you send the wrong class of key, MapWise refuses the request rather than downgrading it. 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 and pricing

API access is included with MapWise Pro, and so is $20 of API usage each month. There is no separate API plan. Above that, you pay for what you use, billed monthly:

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

• County coverage: all 67 Florida counties with complete sales history and parcel 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 has a monthly spend cap, $0 by default, so paid usage is off until you raise it. The cap counts usage above the $20 included with Pro, so with the default cap, billable requests stop at $20 of usage. To change it, open My Account > MapWise API > Monthly Spend Cap. You need the Super Admin or Billing role. The cap can go up to the account maximum of $1,000/month. For higher limits, contact us about enterprise pricing. Once you reach the cap, MapWise declines further billable requests with 429 until usage resets on the 1st of the month (00:00 UTC). MapWise emails you at 80% and 100% of your included usage and of the cap. The 80% emails can be turned off, and a 50% email turned on, in your alert settings.

Security note: a leaked key cannot raise its own cap. Changing the cap needs a signed-in 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. Its body keeps the top-level error field, spend_cap_exceeded, which is still the way to tell it apart from a rate limit. It also carries the members every other failure carries: success, status, errormsg, type, title and detail, plus a top-level code (spend_cap_exceeded) and resets_at, the instant the period resets:

{
  "success": false,
  "status": 429,
  "errormsg": "Your spend cap for this billing period is reached. It resets at 2026-10-01T00:00:00Z.",
  "type": "https://www.mapwise.com/api_v2/problems/spend_cap_exceeded",
  "title": "Spend cap reached",
  "detail": "Your spend cap for this billing period is reached. It resets at 2026-10-01T00:00:00Z.",
  "code": "spend_cap_exceeded",
  "resets_at": "2026-10-01T00:00:00Z",
  "error": "spend_cap_exceeded",
  "endpoint": "parcels",
  "current_spend_cents": 5000,
  "cap_cents": 5000,
  "reset_at": "2026-10-01T00:00:00Z",
  "estimated_call_cost_cents": 6,
  "request_id": "01a0ba0a-e8f4-7fff-853c-bbce832d6c46"
}

Its Retry-After is set to the period reset, which may be days away. Backing off will not help before reset_at, so do not treat it like a rate limit. Raise the cap in My Account, or wait for the reset. Compare current_spend_cents with cap_cents to decide which.

Rate limiting and 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 that, 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:

A request over the limit gets a 429 with a Retry-After header that says when to try again. A 429 can also mean you reached your monthly spend cap, not your rate limit. The body’s error field says which, and its top-level code says the same (spend_cap_exceeded or rate_limited). A value of spend_cap_exceeded means waiting will not help until the period resets. Either way, back off exponentially. Do not retry in a tight loop.

These limits are defaults, not ceilings. For more throughput, contact us.

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 — NAIP Latest CIR aerials-naip-latest-cir

NAIP latest color infrared · USDA NAIP. TileJSON: https://www.mapwise.com/api_v2/tiles/aerials-naip-latest-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, aerials-naip-latest-cir) 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), 429 (monthly spend cap reached, code spend_cap_exceeded, or a rate limit) 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 $0 by default, so paid tile requests are off until you set it under My Account → MapWise API. Tile requests are declined once it is reached.

Error responses

Every failure has this shape. Failures also carry the problem members type, title and detail (RFC 9457) and a top-level snake_case code, such as rate_limited, which is stable and safe to branch on. The existing error field, where a body has one, is unchanged. The spend-cap 429 adds fields of its own, described under Monthly spend caps.

{
  "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.

If a refusal has a machine-readable reason, branch on that, not on errormsg. The errormsg text is written for a person and can change. When a key gate refuses a request, the reason is at data.code: for example, KEY_CLASS_MISMATCH when a key of the wrong class is used. When a path does not route, the reason is at the top level.

Every response carries an X-Request-Id, including failures. It identifies that one request in our logs. Include it when you contact us, so we can find what happened without searching. To correlate with your own logs, send your own ID. It can be up to 64 letters, digits and hyphens. We use yours instead of ours, so make it 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 see whether any results came back.
• 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. The spend-cap 429 adds fields of its own (see Monthly spend caps).
• Give each integration its own secret key. Rotate it with the rotation steps, which overlap the old and new keys so nothing fails in between.

Contact and support

For questions about the API, higher rate limits or enterprise pricing, contact us.