MapView API

Overview

The MapView API answers the questions people ask about an Australian property, with the same answers the MapView app shows:

• Scores: the MapView Score, plus Liveability, Walkability, Crime, Noise & Disturbance and Extension Potential, each with the rows that make it.
• Must Knows: the hazard verdict (flood, bushfire, contamination, mineshafts), the hazards checked and the encumbrances on the lot.
• Planning permits: applications lodged near a property, nearest first, with the council’s own status words.
• Addresses: suggestions with G-NAF place ids, to pin every other call to the right lot.

Every response says what it cost and, for scores, which version of the rules produced it.

Base URL

https://api.mapview.ai/v1

Authentication

Send your organisation’s API key as a bearer token:

Authorization: Bearer mv_live_…

Keys come from the partner portal. The same key works for co-branded reports and for the data API. Keep keys on your server: a key in a browser or mobile app can be copied and billed to you.

Credits and plans

Each call costs credits. The cost is fixed per endpoint and printed below; failed calls cost nothing.

Every response carries three headers:

The Free plan stops at its monthly credits. Paid plans carry on into overage, billed per credit at the end of the month. See plans and prices.

Errors

Errors are JSON with a stable code:

{ "error": "credits_exhausted", "message": "This month's 100 credits are used. Upgrade for more." }

Usage

GET /usage returns your plan, this month’s credits used and remaining, and calls by product. It costs nothing.

curl https://api.mapview.ai/v1/usage -H "Authorization: Bearer $MAPVIEW_KEY"

{
  "data": {
    "plan": { "code": "starter", "name": "Starter", "monthlyCredits": 10000, "overage": true },
    "used": 1240,
    "remaining": 8760,
    "byProduct": [{ "product": "permits.search", "calls": 310, "credits": 930 }]
  },
  "meta": { "credits": 0, "creditsUsedThisMonth": 1240 }
}

Address suggestions

GET /addresses/suggest?q= returns up to ten suggestions for at least three characters. Pass a suggestion’s placeId to the scores endpoints to pin them to that exact lot.

curl "https://api.mapview.ai/v1/addresses/suggest?q=18%20Murphy%20St%20Richmond" -H "Authorization: Bearer $MAPVIEW_KEY"

{ "data": [{ "text": "18 Murphy Street, Richmond VIC 3121", "placeId": "GAVIC421062846" }], "meta": { "credits": 1 } }

Planning permits

GET /permits returns planning applications lodged near a point, nearest first.

curl "https://api.mapview.ai/v1/permits?lat=-37.8231&lng=144.9937&radius=500&since=2025-01-01" \
  -H "Authorization: Bearer $MAPVIEW_KEY"

{
  "data": [
    {
      "reference": "PLN25/0901",
      "description": "Demolition of the existing dwelling and construction of two dwellings",
      "address": "2 Kent Street, Richmond",
      "receivedDate": "2025-11-02",
      "decision": "approved",
      "status": "Permit issued",
      "distanceM": 60,
      "lat": -37.8226,
      "lng": 144.9941,
      "sourceUrl": "https://…"
    }
  ],
  "meta": { "credits": 3, "creditsUsedThisMonth": 1243, "total": 14, "radiusM": 500 }
}

decision is MapView’s reading of the council’s status. status is the council’s own wording when it is words; it is null when the council only publishes a code.

One permit. GET /permits/{reference}?lat=&lng= returns one application, found within 1 km of the point given. Every permit in a search result carries its point. References match whatever the council’s spacing or padding.

Coverage. GET /permits/coverage?lat=&lng=&state= says whether the council at a point feeds permits to MapView (coverage 1, 0.5 or 0) and when it was last updated. Check it before reading “no permits” as “nothing lodged”.

Scores

GET /scores returns the MapView Score and every grid score for a property.

curl "https://api.mapview.ai/v1/scores?lat=-37.8231&lng=144.9937&state=VIC&suburb=Richmond&postcode=3121" \
  -H "Authorization: Bearer $MAPVIEW_KEY"

{
  "data": {
    "overall": { "status": "scored", "score": 72, "band": "Mixed", "caveat": null },
    "scores": {
      "liveability": { "state": "resolved", "score": 81, "tier": "excellent", "word": "Good", "note": "Supermarket 400 m by road", "rows": [] },
      "walkability": { "state": "resolved", "score": 88, "tier": "excellent", "word": "Very Walkable" },
      "crime": { "state": "resolved", "score": 58, "tier": "moderate", "word": "Average" },
      "noise": { "state": "notMapped", "score": null },
      "extension": { "state": "resolved", "score": 67, "tier": "moderate", "word": "Partly suitable" }
    }
  },
  "meta": { "credits": 10, "rulesVersion": "e81e0d37+fe8c3278" }
}

A score is 0 to 100, and higher is always better: a high Crime score means less crime than the state rate, and a high Noise score means quiet. Tiers: 75 and up is excellent, 50 to 74 moderate, below 50 limited.

A score that can’t be measured says so instead of guessing: state is notMapped (no data here) or notApplicable (for example, Extension Potential on public land). The overall is withheld, with a reason, when a hazard that would change it isn’t mapped.

One score. GET /scores/{category} returns one of liveability, walkability, crime, noise or extension, for 3 credits.

Rules version. meta.rulesVersion names the scoring rules that produced the answer. When MapView changes a scoring rule, the version changes, so you can tell a changed answer from a changed property.

Must Knows

GET /must-knows takes the same parameters as /scores and returns the hazard verdict:

{
  "data": {
    "state": "resolved",
    "verdict": "caution",
    "word": "Check",
    "reason": "Heritage overlay; flood not flagged",
    "uncheckedHazards": [],
    "hazards": [{ "label": "Flood", "value": "Not flagged" }],
    "encumbrances": { "easements": [] }
  },
  "meta": { "credits": 5, "rulesVersion": "e81e0d37+fe8c3278" }
}

verdict is clear, caution, flagged or unchecked. uncheckedHazards names any hazard that couldn’t be checked at this lot. Read an empty list as “all checked”, never as “no hazards”.

Limits

Need more? Talk to us.

Co-branded reports

Property and suburb PDF reports with your branding have their own endpoints. See the Co-branded Reports API. The same key works for both.

Machine-readable reference

The OpenAPI document for these endpoints is at https://api.mapview.ai/v1/openapi.json. This page is also available as Markdown for AI coding tools.