# MapView API

https://mapview.ai/developers/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**

```text
https://api.mapview.ai/v1
```

## Authentication

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

```text
Authorization: Bearer mv_live_…
```

Keys come from the [partner portal](/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.

| Endpoint | Credits |
|---|---:|
| `GET /usage` | 0 |
| `GET /addresses/suggest` | 1 |
| `GET /permits` | 3 |
| `GET /permits/{reference}` | 1 |
| `GET /permits/coverage` | 1 |
| `GET /scores` | 10 |
| `GET /scores/{category}` | 3 |
| `GET /must-knows` | 5 |

Every response carries three headers:

| Header | Meaning |
|---|---|
| `X-Credits-Charged` | What this call cost |
| `X-Credits-Used` | Credits used so far this month, including this call |
| `X-Credits-Monthly` | Your plan's monthly credits |

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](/business#pricing).

## Errors

Errors are JSON with a stable code:

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

| Status | `error` | What to do |
|---:|---|---|
| 400 | `invalid_request` | Fix the request. A point must be in Australia; the message says which field. |
| 401 | `unauthorized` | Check the key. |
| 402 | `credits_exhausted` | The month's credits are used. Upgrade, or wait for the 1st. |
| 403 | `organisation_inactive` | Your organisation is suspended. Contact us. |
| 404 | `not_found` | Nothing at that reference or point. |
| 429 | `rate_limited` | Too many calls a second for your plan. Retry after the `Retry-After` header. |
| 502 | `upstream_unavailable` | A source didn't answer. Retry shortly; you weren't charged. |
| 503 | `api_unavailable` | The API is down for maintenance. Retry shortly. |

## Usage

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

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

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

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

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

| Parameter | Required | Meaning |
|---|---|---|
| `lat`, `lng` | Yes | The property |
| `radius` | No | Metres, 50 to 1000. Default 500. |
| `since` | No | Only applications received on or after this date (`YYYY-MM-DD`) |
| `decision` | No | `approved`, `in_progress`, `refused` or `under_review` |
| `limit` | No | 1 to 50. Default 20. `meta.total` says how many matched. |

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

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

| Parameter | Required | Meaning |
|---|---|---|
| `lat`, `lng` | Yes | The property |
| `state` | Recommended | `VIC`, `NSW`, `QLD`, `SA`, `WA`, `TAS`, `NT` or `ACT` |
| `suburb`, `postcode`, `address` | Recommended | The address parts, for the lot lookups |
| `placeId` | Recommended | The G-NAF id from `/addresses/suggest`, which pins the lot |

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

```json
{
  "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:

```json
{
  "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

| Plan | Calls a second |
|---|---:|
| Free | 2 |
| Starter | 5 |
| Growth | 10 |
| Scale | 25 |
| Enterprise | 50 or more |

Need more? [Talk to us](/contact).

## Co-branded reports

Property and suburb PDF reports with your branding have their own endpoints. See the [Co-branded Reports API](/developers/co-branded-reports). 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](/developers/api.md) for AI coding tools.