> ## Documentation Index > Fetch the complete documentation index at: https://docs.prontiq.dev/llms.txt > Use this file to discover all available pages before exploring further. # Postcode Lookup > List suburbs or localities that have address records in a four-digit Australian postcode. Use this for postcode-first forms, locality dropdowns, and coverage checks. `address_count` is dataset cardinality, not billing usage. Use Postcode Lookup when your input is a 4-digit postcode and you need matching localities with address counts. For examples and field notes, see the [Postcode lookup guide](/guides/address/postcode-lookup). ## OpenAPI ````yaml GET /v1/address/lookup/postcode openapi: 3.1.0 info: title: Prontiq API version: 2.0.0 license: name: Proprietary url: https://prontiq.dev description: >- Prontiq provides authenticated APIs for Australian address search, validation, enrichment, reverse geocoding, and locality lookup. Authenticate public data requests with `X-Api-Key`. Successful Address API calls may include rate-limit and credit-usage headers. Errors use a stable `{ error: { code, message, status, request_id } }` envelope; `request_id` is intentionally snake_case for v1 compatibility. servers: - url: https://api.prontiq.dev description: Production API security: [] tags: - name: Address description: >- Australian address autocomplete, validation, enrichment, reverse geocoding, postcode lookup, and suburb lookup. paths: /v1/address/lookup/postcode: get: tags: - Address summary: Look up localities by postcode description: >- List suburbs or localities that have address records in a four-digit Australian postcode. Use this for postcode-first forms, locality dropdowns, and coverage checks. `address_count` is dataset cardinality, not billing usage. operationId: lookupPostcode parameters: - schema: type: string pattern: ^\d{4}$ description: Australian 4-digit postcode. example: '2000' required: true description: Australian 4-digit postcode. name: postcode in: query - schema: type: integer minimum: 1 maximum: 50 default: 10 description: Maximum number of localities to return. example: 3 required: false description: Maximum number of localities to return. name: limit in: query - schema: $ref: '#/components/schemas/AddressDebugQuery' required: false description: >- Optional diagnostic flag. Send exactly `true` or `false`. Invalid values are rejected; debug diagnostics are for support only and must not be used for business decisions. name: debug in: query responses: '200': description: Localities and address counts for the requested postcode. headers: X-Request-Id: description: Unique request identifier for support and debugging. schema: type: string X-RateLimit-Product: description: >- API family whose monthly credit counter was updated, for example `address`. schema: type: string X-RateLimit-Reset: description: ISO timestamp when the current credit window resets. schema: type: string format: date-time X-RateLimit-Limit: description: >- Configured included-credit threshold for keys with a monthly quota. Present for hard-cap and soft-overage plans; omitted for PAYG or uncapped plans. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: >- Included credits remaining in the current window, floored at zero. Present for hard-cap and soft-overage plans; omitted for PAYG or uncapped plans. schema: type: integer minimum: 0 X-RateLimit-Over: description: >- `true` when the request succeeded as soft-overage after included credits were exceeded. schema: type: string enum: - 'true' X-Payment-Overdue: description: >- Indicates whether the account currently has an overdue billing state. Request handling still follows the active plan enforcement policy. schema: type: string enum: - 'true' content: application/json: schema: $ref: '#/components/schemas/PostcodeLookupResponse' example: postcode: '2000' localities: - name: SYDNEY state: NSW address_count: 12345 '400': description: >- The request query string is missing a required parameter or contains a value outside the documented format. content: application/json: schema: $ref: '#/components/schemas/AddressErrorResponse' example: error: code: INVALID_PARAMETERS message: Invalid query parameters status: 400 request_id: req_01HZX7A8J5K9P4R2QW3E6T7Y8Z details: q: - Required '401': description: The request did not include a valid `X-Api-Key` header. content: application/json: schema: $ref: '#/components/schemas/AddressErrorResponse' example: error: code: MISSING_API_KEY message: Missing X-Api-Key header status: 401 request_id: req_01HZX7A8J5K9P4R2QW3E6T7Y8Z '403': description: >- The API key is valid, but the account plan does not include the Address API product. content: application/json: schema: $ref: '#/components/schemas/AddressErrorResponse' example: error: code: PRODUCT_NOT_ALLOWED message: Product not included in your plan status: 403 request_id: req_01HZX7A8J5K9P4R2QW3E6T7Y8Z '429': description: >- The request exceeded burst rate limits or the account's available Address API quota. headers: Retry-After: description: >- Seconds to wait before retrying when error.code is RATE_LIMITED. Quota exhaustion responses may omit this header. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/AddressErrorResponse' example: error: code: RATE_LIMITED message: Rate limit exceeded status: 429 request_id: req_01HZX7A8J5K9P4R2QW3E6T7Y8Z '500': description: >- The API could not complete the request because of an unexpected server-side failure. content: application/json: schema: $ref: '#/components/schemas/AddressErrorResponse' example: error: code: INTERNAL_ERROR message: Internal server error status: 500 request_id: req_01HZX7A8J5K9P4R2QW3E6T7Y8Z security: - ApiKeyAuth: [] components: schemas: AddressDebugQuery: type: string enum: - 'true' - 'false' description: >- Optional diagnostic flag. Send exactly `true` or `false`. Invalid values are rejected; debug diagnostics are for support only and must not be used for business decisions. example: 'false' PostcodeLookupResponse: type: object properties: postcode: $ref: '#/components/schemas/Postcode' localities: type: array items: $ref: '#/components/schemas/PostcodeLocalitySummary' description: >- Localities that contain address records for the requested postcode, ordered by the lookup implementation. example: - name: SYDNEY state: NSW address_count: 12345 debug: $ref: '#/components/schemas/DebugInfo' required: - postcode - localities description: Localities and address counts for an Australian postcode. AddressErrorResponse: type: object properties: error: type: object properties: code: $ref: '#/components/schemas/AddressErrorCode' message: type: string description: Human-readable error message. example: Invalid query parameters status: type: integer description: HTTP status code. example: 400 request_id: type: string description: >- Request identifier for support and debugging. This snake_case field is stable in v1. example: req_01HZX7A8J5K9P4R2QW3E6T7Y8Z details: type: object additionalProperties: {} description: Optional structured details. Shape depends on the error code. example: q: - Required required: - code - message - status - request_id description: >- Nested error object containing the machine code, human message, HTTP status, and request id. example: code: INVALID_PARAMETERS message: Invalid query parameters status: 400 request_id: req_01HZX7A8J5K9P4R2QW3E6T7Y8Z required: - error description: >- Standard public Address API error envelope. The nested `error.request_id` field is intentionally snake_case in v1. Postcode: type: string pattern: ^\d{4}$ description: >- Four-digit Australian postcode. Store postcodes as strings; integer coercion can remove leading zeroes used by some Australian postcodes. example: '4703' PostcodeLocalitySummary: type: object properties: name: type: string description: Official suburb or locality name associated with the postcode. example: SYDNEY state: anyOf: - $ref: '#/components/schemas/AustralianStateCode' - type: 'null' description: >- Australian state or territory for the locality when available. The value is uppercase in responses. example: NSW address_count: type: integer minimum: 0 description: >- Number of address records in this locality for the requested postcode. This is dataset cardinality, not credit usage. example: 12345 required: - name - address_count description: Locality summary returned for a postcode lookup. example: name: SYDNEY state: NSW address_count: 12345 DebugInfo: type: object properties: scoringVersion: type: string enum: - address-match-v1 description: >- Version of the public Prontiq match-scoring algorithm used for diagnostics. example: address-match-v1 queryMode: type: string enum: - autocomplete - validate - enrich - reverse - lookup description: Address API operation mode that produced this diagnostic object. example: autocomplete matchedComponents: type: object additionalProperties: type: string enum: - exact - prefix - fuzzy - none description: >- Per-component match classification for diagnostics. Shape may evolve between scoring versions. example: streetNumber: exact streetName: prefix locality: exact scoreCaps: type: array items: type: string description: >- Diagnostic list of caps applied to the score, such as explicit postcode or state mismatches. example: - explicitPostcodeMismatch searchScore: type: number description: >- Internal search relevance score when available. This value is unstable and must not be stored, sorted by, or used for business decisions. format: double example: 42.1 required: - scoringVersion - queryMode description: >- Optional diagnostic metadata returned only when `debug=true` is supplied. Debug values are for support and troubleshooting, not production decision-making. example: scoringVersion: address-match-v1 queryMode: autocomplete searchScore: 42.1 AddressErrorCode: type: string enum: - INVALID_API_KEY - MISSING_API_KEY - RATE_LIMITED - QUOTA_EXCEEDED - PRODUCT_NOT_ALLOWED - INVALID_PARAMETERS - NOT_FOUND - INTERNAL_ERROR description: >- Stable machine-readable public Address API error code. Use this value for branching instead of parsing the human-readable `message`. example: INVALID_PARAMETERS AustralianStateCode: type: string enum: - NSW - VIC - QLD - SA - WA - TAS - NT - ACT description: >- Uppercase Australian state or territory code returned by the Address API. Allowed values are `NSW` New South Wales, `VIC` Victoria, `QLD` Queensland, `SA` South Australia, `WA` Western Australia, `TAS` Tasmania, `NT` Northern Territory, and `ACT` Australian Capital Territory. example: QLD securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key ````