---
title: "EP-19 — Country Detail"
url: "https://dev.ionova.ai/apis/ars-address-resolution-service-4/versions/fdd2c316-7f84-4f04-8bb7-64e9bf97893b/operations/getCountryDetail"
---

> Full API specification: https://dev.ionova.ai/apis/ars-address-resolution-service-4/versions/fdd2c316-7f84-4f04-8bb7-64e9bf97893b.md

# EP-19 — Country Detail

`GET` `/countries/{code}`

Operation ID: `getCountryDetail`

Returns full country detail including PMPG element usage indicators for all 14 PostalAddress24 structured fields. Returns HTTP 404 if code not found.

## Path parameters

- `code` (string, required) - ISO 3166-1 alpha-2 country code (e.g. DE, GB, CH)

## Header parameters

- `X-Request-ID` (string, uuid, optional) - Client-supplied correlation ID echoed in response headers for tracing.

## Responses

- `200` - Country detail returned
- `401` - Unauthorized — missing or invalid authentication credentials.
- `404` - Not Found — the requested resource does not exist.
- `500` - Internal Server Error — unexpected server-side failure.

## OpenAPI definition

```yaml
openapi: 3.0.3
info:
  title: ARS — Address Resolution Service
  version: 4.3.1
servers:
  - url: https://api-uat.ionova.ai/ars
    description: UAT (test data only)
paths:
  /countries/{code}:
    get:
      tags:
        - Layer 4 — Reference
      summary: EP-19 — Country Detail
      description: >
        Returns full country detail including PMPG element usage indicators for
        all

        14 PostalAddress24 structured fields. Returns HTTP 404 if code not
        found.
      operationId: getCountryDetail
      parameters:
        - $ref: "#/components/parameters/XRequestId"
        - name: code
          in: path
          required: true
          description: ISO 3166-1 alpha-2 country code (e.g. DE, GB, CH)
          schema:
            type: string
            pattern: ^[A-Z]{2}$
            example: DE
      responses:
        "200":
          description: Country detail returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CountryDetailResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - ApiKeyAuth: []
security:
  - ApiKeyAuth: []
components:
  parameters:
    XRequestId:
      name: X-Request-ID
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: Client-supplied correlation ID echoed in response headers for tracing.
  schemas:
    CountryDetailResponse:
      type: object
      xml:
        name: CountryDetailResponse
      properties:
        code:
          type: string
          pattern: ^[A-Z]{2}$
        name:
          type: string
        sepaMember:
          type: boolean
        eeaMember:
          type: boolean
        elementUsage:
          type: object
          description: PMPG usage indicators for all 14 PostalAddress24 structured fields.
            M=Mandatory, E=Expected, O=Optional, C=Conditional, N=Not used.
          properties:
            streetName:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            buildingNumber:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            buildingName:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            floor:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            postBox:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            room:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            postCode:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            townName:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            townLocationName:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            districtName:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            countrySubDivision:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            country:
              $ref: "#/components/schemas/PmpgUsageIndicator"
            addressLine:
              $ref: "#/components/schemas/PmpgUsageIndicator"
    PmpgUsageIndicator:
      type: string
      description: >
        PMPG element usage indicator for a PostalAddress24 field in a given
        country.

        M=Mandatory, E=Expected, O=Optional, C=Conditional, N=Not used.
      enum:
        - M
        - E
        - O
        - C
        - N
    ErrorResponse:
      type: object
      xml:
        name: ErrorResponse
      description: Standard error envelope returned on 4xx and 5xx responses.
      properties:
        code:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Human-readable error description.
        requestId:
          type: string
          description: Correlation ID for support.
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: 401
            message: Authentication credentials are missing or invalid.
            requestId: b1a2c3d4-0000-0000-0000-000000000001
        application/xml:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example: >
            <?xml version="1.0" encoding="UTF-8"?>

            <ErrorResponse>
              <code>401</code>
              <message>Authentication credentials are missing or invalid.</message>
              <requestId>b1a2c3d4-0000-0000-0000-000000000001</requestId>
            </ErrorResponse>
    NotFound:
      description: Not Found — the requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: 404
            message: The requested resource was not found.
            requestId: b1a2c3d4-0000-0000-0000-000000000002
        application/xml:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example: |
            <?xml version="1.0" encoding="UTF-8"?>
            <ErrorResponse>
              <code>404</code>
              <message>The requested resource was not found.</message>
              <requestId>b1a2c3d4-0000-0000-0000-000000000002</requestId>
            </ErrorResponse>
    InternalServerError:
      description: Internal Server Error — unexpected server-side failure.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: 500
            message: An unexpected error occurred. Please contact support with your
              requestId.
            requestId: b1a2c3d4-0000-0000-0000-000000000006
        application/xml:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example: |
            <?xml version="1.0" encoding="UTF-8"?>
            <ErrorResponse>
              <code>500</code>
              <message>An unexpected error occurred.</message>
              <requestId>b1a2c3d4-0000-0000-0000-000000000006</requestId>
            </ErrorResponse>
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your ioNova platform API key. Generate it from your organisation
        admin in the ioNova app, then paste it here to test.
```