Documentation

Code Examples

Use this guide to call Addresses API v2 from curl, JavaScript, Python, or Java and handle response changes.

Code
export GEOSCAPE_API_KEY="YOUR_CONSUMER_KEY"

Keep the Consumer Secret out of these requests. It is not used by the REST endpoints documented here.

curl

Code
curl "https://api.psma.com.au/v2/addresses/geocoder?address=1%20Swanston%20Street%20Melbourne%20VIC%203000" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/geo+json"

JavaScript (Node.js)


Code
const apiKey = process.env.GEOSCAPE_API_KEY;
const response = await fetch(
  "https://api.psma.com.au/v2/addresses/geocoder?address=1%20Swanston%20Street%20Melbourne%20VIC%203000",
  {
    headers: {
      Authorization: apiKey,
      Accept: "application/geo+json",
    },
  },
);

if (!response.ok) {
  throw new Error(`Geoscape request failed: ${response.status}`);
}

const geojson = await response.json();

Python


Code
import os
import requests

response = requests.get(
    "https://api.psma.com.au/v2/addresses/geocoder",
    params={"address": "1 Swanston Street Melbourne VIC 3000"},
    headers={
        "Authorization": os.environ["GEOSCAPE_API_KEY"],
        "Accept": "application/geo+json",
    },
    timeout=30,
)
response.raise_for_status()
geojson = response.json()

Java (JVM)

This example uses the Java 11+ HttpClient API:


Code
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.psma.com.au/v2/addresses/geocoder?address=1%20Swanston%20Street%20Melbourne%20VIC%203000"))
    .header("Authorization", System.getenv("GEOSCAPE_API_KEY"))
    .header("Accept", "application/geo+json")
    .GET()
    .build();

var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

if (response.statusCode() >= 400) {
    throw new IllegalStateException("Geoscape request failed: " + response.statusCode());
}

String geojson = response.body();

Handling response changes

New response properties are additive. Ignore unknown properties when deserialising responses and read only the fields your application needs. If you use typed models, configure the deserialiser to allow additional properties instead of treating them as errors.

For example, read only the documented features field so these clients tolerate other fields added to the response:


Code
const { features } = geojson;


Code
geojson = response.json()
features = geojson.get("features", [])

With Jackson, read only the fields your application needs:


Code
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();
JsonNode body = mapper.readTree(response.body());
JsonNode features = body.path("features");

Fields added to the response remain available in body but do not affect this code.

Removing a response property can break clients that depend on it. Check the current reference when upgrading and handle optional and deprecated fields safely.

Maps API

Mapping libraries can use the Maps API key query parameter when they cannot set an authorization header:

Code
https://api.psma.com.au/v1/maps/geoscape_v1/gnaf/{z}/{x}/{y}.pbf?key=YOUR_CONSUMER_KEY

See Maps API: Quickstart for a complete MapLibre example.

Next steps

Last modified on October 29, 2026

JavaScript (Node.js)

Code

const apiKey = process.env.GEOSCAPE_API_KEY;
const response = await fetch(
  "https://api.psma.com.au/v2/addresses/geocoder?address=1%20Swanston%20Street%20Melbourne%20VIC%203000",
  {
    headers: {
      Authorization: apiKey,
      Accept: "application/geo+json",
    },
  },
);

if (!response.ok) {
  throw new Error(`Geoscape request failed: ${response.status}`);
}

const geojson = await response.json();

Python

Code

import os
import requests

response = requests.get(
    "https://api.psma.com.au/v2/addresses/geocoder",
    params={"address": "1 Swanston Street Melbourne VIC 3000"},
    headers={
        "Authorization": os.environ["GEOSCAPE_API_KEY"],
        "Accept": "application/geo+json",
    },
    timeout=30,
)
response.raise_for_status()
geojson = response.json()

Java (JVM)

This example uses the Java 11+ HttpClient API:

Code

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.psma.com.au/v2/addresses/geocoder?address=1%20Swanston%20Street%20Melbourne%20VIC%203000"))
    .header("Authorization", System.getenv("GEOSCAPE_API_KEY"))
    .header("Accept", "application/geo+json")
    .GET()
    .build();

var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

if (response.statusCode() >= 400) {
    throw new IllegalStateException("Geoscape request failed: " + response.statusCode());
}

String geojson = response.body();

Handling response changes

For example, read only the documented features field so these clients tolerate other fields added to the response:

Code

const { features } = geojson;

Code

geojson = response.json()
features = geojson.get("features", [])

With Jackson, read only the fields your application needs:

Code

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();
JsonNode body = mapper.readTree(response.body());
JsonNode features = body.path("features");

Fields added to the response remain available in body but do not affect this code.

Removing a response property can break clients that depend on it. Check the current reference when upgrading and handle optional and deprecated fields safely.