MapWise API

Quick Start

Get started in 3 steps

1. Try the test endpoint — no API key needed. Make a request to /parcels/test to see the response format.
2. Get your API key — 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. The account owner or billing admin logs in and opens My Account → Parcels API, then creates a key.
3. Query the full endpoint — use your API key with /parcels to access all 67 Florida counties.

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.

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

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

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.

Create either kind in My Account → Parcels API. API access is included with MapWise Pro; issuing keys needs the Super Admin role.

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 → Parcels 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

Limits are per API key, and map tiles are counted separately from data so that panning a map cannot exhaust the budget your data calls need:

• Data endpoints: 10 requests per second, sustained. The allowance refills continuously, and you can spend up to 600 requests at once before it does — enough for a burst of parallel lookups, after which you are held to the sustained rate.
• Map tiles and WMS: 60 requests per second. A single pan or zoom fetches dozens of tiles, so these get their own, faster budget.
• The keyless /parcels/test endpoint: 5 requests per second for anonymous callers. Use a key and the full /parcels endpoint for the limits above.

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

X-RateLimit-Bucket-Capacity: 600
X-RateLimit-Bucket-Remaining: 587
X-RateLimit-Endpoint-Limit: 60

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.
• Rotate API keys regularly and use HTTPS for all requests.
• Monitor your API usage and rate limits.

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.

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.

Contact & Support

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