# Code Examples

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

```shell
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

```shell
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)

```javascript
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

```python
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:

```java
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:

```javascript
const { features } = geojson;
```

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

With Jackson, read only the fields your application needs:

```java
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:

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

See [Maps API: Quickstart](/guides/maps/getting-started) for a complete MapLibre example.

## Next steps

- [Browse the API Reference](/reference)
- [Handle errors and retries](/guides/errors)
- [Handle request rates](/guides/rate-limiting)