MapWise reports

Get a parcel report with the API

Make a PDF report for any Florida parcel with one call. You send the parcel and the report type. MapWise stores the report and gives you links to its PDF and a page-one preview.

Reports use your secret API key, as other API calls do. Create one in My Account > MapWise API.

Report types

Send one of these as type. Each report covers one parcel.

typeReportWhat it shows
propertyProperty reportOwner, sales, building, values, legal description and soils for the parcel.
floodFlood reportThe flood zones on the parcel, with its NFIP and coastal barrier status.

Check before you create

GET /api_v2/reports/allowance says which report types your key can create on this host, and the sections each one prints. It is free.

  • available is true for a type you can create now.
  • When it is false, reason says why.
  • Each type has a sample_url: a sample PDF you can open without a key.
Request
curl https://www.mapwise.com/api_v2/reports/allowance \
  -H "X-API-Key: mw_sk_…"
Response (trimmed)
{
    "success": true,
    "data": {
        "billing": "metered",
        "quota": null,
        "types": {
            "property": {
                "available": true,
                "reason": null
            },
            "flood": {
                "available": true,
                "reason": null
            }
        }
    }
}

Create a report

Send POST /api_v2/reports with a JSON body:

  • type: one of the report types above.
  • subject.kind: parcel.
  • subject.pin: the parcel ID, as the parcel search returns it.
  • subject.metadata.county: the parcel's county, such as PINELLAS.
  • title (optional): the report's name. Left out, it is the parcel's address and the type.

A new report answers 201. That answer is the one that bills.

Request
curl https://www.mapwise.com/api_v2/reports \
  -H "X-API-Key: mw_sk_…" \
  -H "Idempotency-Key: 6f1c2b9e-0d4a-4e8b-9a51-3c7d2e8f1a40" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "property",
    "subject": {
        "kind": "parcel",
        "pin": "163004775150002200",
        "metadata": {
            "county": "PINELLAS"
        }
    }
}'

Retry safely

Send an Idempotency-Key header with every create. Use a new random value, such as a UUID, for each new report. If a request goes unanswered, send it again with the same key and the same body.

  • A retry after a 201 returns the same report and is not billed again. It carries the header Idempotent-Replayed: true.
  • A retry while the first request is still running answers 409 with Retry-After: 2. Wait, then retry with the same key.
  • The same key with a different body answers 422.
  • A key lasts 24 hours.

The response

data says which report you made and where to get it:

  • id: the report's ID. Keep it to fetch the report again with GET /api_v2/reports/{id}.
  • download_url: a link to the PDF that anyone can open, with no key. It expires at expires_at, 15 minutes after it was made.
  • pdf_url: the PDF for your key. It does not expire.
  • preview_url: an image of page one, or null until one is ready.

meta.record_count is 1 on a new report: the report you were billed for.

data
{
    "id": "rpt_3f2b8c1e-9d4a-4b7e-8f60-2a1c5d9e7b43",
    "type": "property",
    "title": "13600 Icot Blvd",
    "status": "active",
    "download_url": "https://www.mapwise.com/api_v2/reports/download/\u2026",
    "expires_at": "2026-10-20T14:15:00+00:00",
    "preview_url": null,
    "pdf_url": "/api_v2/reports/rpt_3f2b8c1e-9d4a-4b7e-8f60-2a1c5d9e7b43/pdf"
}

Get the PDF

Fetch pdf_url with your key. The answer is the PDF itself.

  • GET /api_v2/reports/{id}/preview?size=thumb or size=page returns page one as an image.
  • A 503 means the renderer is busy. Wait for Retry-After seconds, then try again.
  • Downloads and previews are never billed.
Request
curl https://www.mapwise.com/api_v2/reports/rpt_…/pdf \
  -H "X-API-Key: mw_sk_…" \
  -o report.pdf

When nothing is charged

Only a 201 bills. Every other answer stores nothing and costs nothing:

  • 400: the body is missing a field or has an unknown type.
  • 403: your key cannot create that type here. data.reason says why.
  • 404 or 422: the parcel was not found, or the PIN matched more than one parcel.
  • 429: the report would pass your monthly spend cap, or you sent too many requests.
  • 503: a service the report needs is busy. Retry after Retry-After seconds.

Branch on data.error_code and the status, not on the message text.

Price and spend cap

Each report$1.00 / report

Reports bill with the rest of your API use. They count toward the monthly spend cap you set in My Account > MapWise API.

Use GET /api_v2/reports/allowance before a batch. It is free, and it tells you which types each key can create.