GenieSearchResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-genie-search-response-schema.json",
  "title": "GenieSearchResponse",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-genie-transaction-enrichment-api-openapi.yml#/components/schemas/GenieSearchResponse",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "enum": [
        true
      ]
    },
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/GenieSearchQueryResult"
      }
    }
  },
  "required": [
    "success",
    "items"
  ],
  "$defs": {
    "GenieAddress": {
      "type": "object",
      "required": [
        "street",
        "city",
        "region",
        "country",
        "postal_code"
      ],
      "properties": {
        "street": {
          "type": "string"
        },
        "suburb": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "region": {
          "type": "string"
        },
        "country": {
          "type": "string"
        },
        "postal_code": {
          "type": "string"
        }
      }
    },
    "GenieCategory": {
      "type": "object",
      "description": "A category classification result from Genie. This classification provides the base [NZFCC](https://nzfcc.org) category code for the transaction. Additionally, the `groups` attribute includes a mapping of the NZFCC category into broader (less-specific) category groups. Category grouping is based on mappings which are able to be customised per-client. The `personal_finance` mapping is included by default.",
      "properties": {
        "_id": {
          "type": "string",
          "description": "The [NZFCC](https://nzfcc.org) category code for the transaction"
        },
        "name": {
          "type": "string",
          "description": "The name of the NZFCC category for this transaction"
        },
        "groups": {
          "type": "object",
          "description": "A dictionary of category groups, keyed by category mapping name, for the NZFCC base category.",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "_id": {
                "type": "string",
                "description": "The category group identifier for this mapping."
              },
              "name": {
                "type": "string",
                "description": "The category group name for this mapping."
              }
            }
          }
        }
      },
      "required": [
        "_id",
        "name",
        "groups"
      ]
    },
    "GenieCoordinates": {
      "type": "object",
      "description": "Latitude/longitude location coordinates.",
      "required": [
        "lat",
        "lon"
      ],
      "properties": {
        "lat": {
          "type": "number"
        },
        "lon": {
          "type": "number"
        }
      }
    },
    "GenieLocation": {
      "type": "object",
      "description": "A physical location.",
      "required": [
        "accuracy",
        "formatted",
        "coordinates"
      ],
      "properties": {
        "accuracy": {
          "type": "string",
          "enum": [
            "country",
            "region",
            "locality",
            "sublocality",
            "establishment"
          ]
        },
        "formatted": {
          "type": "string"
        },
        "coordinates": {
          "$ref": "#/$defs/GenieCoordinates"
        },
        "address": {
          "description": "The address fields in a structured format. This is available on almost all establishment-level locations, however it may occasionally be missing,",
          "allOf": [
            {
              "$ref": "#/$defs/GenieAddress"
            }
          ]
        }
      }
    },
    "GenieMerchant": {
      "type": "object",
      "description": "A merchant match result from Genie.",
      "required": [
        "_id",
        "name",
        "logo"
      ],
      "properties": {
        "_id": {
          "type": "string",
          "description": "The unique merchant identifier."
        },
        "name": {
          "type": "string",
          "description": "The merchant's name (trading name)."
        },
        "logo": {
          "type": "string",
          "description": "A URL referencing the merchant's logo. If no logo is available, a placeholder image is provided."
        },
        "logo_is_placeholder": {
          "type": "boolean",
          "description": "A boolean flag, set to `true` if the `logo` URL points to a placeholder image rather than the merchant's real logo (i.e. there is no logo available for this merchant). This flag may be useful if you would prefer not to display placeholder logos or replace them with your own."
        },
        "website": {
          "type": "string",
          "description": "The URL for the merchant's website."
        },
        "phone": {
          "type": "string",
          "description": "The merchant's phone number."
        },
        "nzbn": {
          "type": "string",
          "description": "The merchant's NZBN (New Zealand Business Number)."
        },
        "location": {
          "description": "The merchant's location.",
          "allOf": [
            {
              "$ref": "#/$defs/GenieLocation"
            }
          ]
        },
        "tags": {
          "type": "array",
          "description": "Tags that apply to the merchant. For example, to indicate that the merchant provides a subscription service.",
          "items": {
            "$ref": "#/$defs/GenieTag"
          }
        }
      }
    },
    "GenieOutlet": {
      "type": "object",
      "description": "An individual outlet (i.e. specific location). An outlet will always be returned in combination with its related \"parent\" merchant.",
      "required": [
        "_id",
        "name"
      ],
      "properties": {
        "_id": {
          "type": "string",
          "description": "The unique outlet identifier."
        },
        "name": {
          "type": "string",
          "description": "The outlet name. This is usually more specific than the merchant name. For example, the merchant name may be \"Pak'nSAVE\", while the outlet name is \"Pak'nSAVE Sylvia Park\"."
        },
        "logo": {
          "type": "string",
          "description": "A URL referencing the outlet's logo. This field will only be included if the logo for this outlet differs from the merchant's logo."
        },
        "website": {
          "type": "string",
          "description": "The URL for the outlet's website. This field will only be included if the website for this outlet differs from the merchant's website."
        },
        "phone": {
          "type": "string",
          "description": "The outlet's phone number. This field will only be included if the phone number for this outlet differs from the merchant's phone number."
        },
        "nzbn": {
          "type": "string",
          "description": "The outlet's NZBN (New Zealand Business Number). This field will only be included if the NZBN for this outlet differs from the merchant's NZBN."
        },
        "location": {
          "description": "The outlet's location.",
          "allOf": [
            {
              "$ref": "#/$defs/GenieLocation"
            }
          ]
        },
        "tags": {
          "type": "array",
          "description": "Tags that apply to the outlet. For example, to indicate that the outlet provides a subscription service. Tags are inherited (and potentially extended) from the outlet's \"parent\" merchant.",
          "items": {
            "$ref": "#/$defs/GenieTag"
          }
        }
      }
    },
    "GenieSearchQueryResult": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The correlation identifier for the query (if you provided one)."
        },
        "query": {
          "type": "string",
          "description": "The original query description as provided."
        },
        "results": {
          "type": "array",
          "description": "The enrichment result for this query. Will contain 1 item if enrichment is successful, otherwise the array will be empty.",
          "items": {
            "type": "object",
            "properties": {
              "confidence": {
                "type": "number",
                "description": "A value between 0 and 0.99 (inclusive) indicating the strength of the matched result (currently the lowest returned confidence score is 0.5)."
              },
              "match_algorithm": {
                "type": "string",
                "description": "An opaque value that identifies the algorithm that generated this enrichment result. This can be used in combination with webhooks to invalidate cached results when algorithms are added or updated by Akahu."
              },
              "match_reference": {
                "type": "string",
                "description": "An opaque value that identifies the specific enrichment rule or matching logic that generated this result. This can be used in combination with webhooks to invalidate cached results when enrichment rules are updated by Akahu."
              },
              "category": {
                "$ref": "#/$defs/GenieCategory",
                "description": "The category assigned to this query by Genie enrichment."
              },
              "merchant": {
                "$ref": "#/$defs/GenieMerchant",
                "description": "The merchant assigned to this query by Genie enrichment."
              },
              "outlet": {
                "$ref": "#/$defs/GenieOutlet",
                "description": "The specific outlet assigned to this query by Genie enrichment.\n\nThis field is only included in the result when a distinct outlet has been identified. For example, \"Pak'nSAVE Mount Albert\".\n\nAn outlet result will not be included for single-location merchants (e.g. your local dairy).\n\nAn outlet result will always be accompanied with a \"parent\" merchant."
              }
            },
            "required": [
              "confidence",
              "category",
              "match_reference",
              "match_algorithm"
            ]
          }
        }
      },
      "required": [
        "query",
        "results"
      ]
    },
    "GenieTag": {
      "type": "string",
      "description": "A tag applied to an outlet or merchant, indicating a specific attribute that applies to that entity.",
      "enum": [
        "subscription",
        "closed"
      ]
    }
  }
}