# API Conventions

Use this guide to understand request formats, response schemas, pagination, and credit usage across the Geoscape APIs. Choose an API from [Get Started](/guides/welcome#choose-an-api) and follow its Quickstart to make your first request.

## Base URLs

Most APIs in this reference use `https://api.psma.com.au`. The [Verify API](/apis/verify#api-conventions) uses `https://api.geoscape.com.au`.

Use the base URL, version, and endpoint path shown in each API's reference.

## Request and response conventions

- APIs use resource-oriented URLs and standard HTTP methods such as `GET` and `POST`.
- Responses are generally JSON or GeoJSON. The endpoint reference specifies the response media type and schema.
- Send the `Accept` header to specify your preferred response media type. See [MDN's Accept header reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) for the HTTP syntax.
- Query parameters, headers, and request bodies are documented on each operation. Use the generated request samples as a starting point.
- Authenticate with your Consumer Key in the `Authorization` header. Maps also supports a `key` query parameter. See [Authentication](/guides/authentication).
- HTTP status codes indicate whether a request succeeded. See [Error Handling](/guides/errors) before implementing retries.

## Request inputs and response fields

- Required request inputs must be supplied in the documented location: path, query, header, or JSON body
- A required response field must be present when its containing object is returned. It is not an instruction to send that field in your request
- Optional response fields can be omitted or returned as `null`, depending on the endpoint. Check the schema and guide before reading them
- Query parameters that accept multiple values normally use one comma-separated value. Use the endpoint’s documented syntax and casing
- Multi-value JSON body fields use arrays where the schema defines an array
- A successful HTTP status means the request was processed. An empty result or a batch job still in progress can also return `200`

## Pagination and returned links

For endpoints with pagination, use the documented page-size and offset parameters. Limits and defaults differ by API.

- Read the returned count fields and follow `links.next` while present
- Resolve relative links against the host used for the request and send the same Consumer Key to that API
- Stop when there is no next link. An empty page does not necessarily mean the original search had no matches
- Follow signed file-download URLs as returned. Do not send your Consumer Key to the storage host

## Credit usage

Where supplied, `x-attr-basictransaction` reports credits charged for the request. Costs differ by endpoint and requested attributes. Batches reports estimated and actual job costs in its response body, and Datasets listings are free. Check the endpoint reference and your Hub subscription for product-specific charging information.

## A practical request workflow

1. Select an API from the [API Reference](/reference). For new integrations, use the latest available API version unless you have a specific compatibility requirement.
2. Check its access requirements and create an application in [Geoscape Hub](https://hub.geoscape.com.au).
3. Try the generated request sample with your Consumer Key.
4. Read the endpoint parameters, response schema, examples, and response codes.
5. Move the request into your application and add throttling, error handling, and attribution as appropriate.

## Next steps

- [Try the Addresses API quickstart](/guides/addresses/quickstart)
- [Review authentication](/guides/authentication), [error handling](/guides/errors), and [rate limiting](/guides/rate-limiting)