NBG Rates (National Bank of Georgia)

Official National Bank of Georgia (NBG) exchange rates of the Georgian lari (GEL) in force on one calendar date. Every rate is GEL per ONE unit of the currency (NBG quotes some currencies per 10, 100, 1000 or 10000 units; the raw pair is returned as nbgQuantity and nbgRate). Dates are calendar days in Tbilisi; the default is today. NBG sets a rate on business days around 17:00 Tbilisi time, valid from the next calendar day until the next rate, so after 17:00 tomorrow can be requested by date. Sundays, Mondays and days after a public holiday have no rate of their own: the rate in force was set earlier and is returned with carriedOver true and effectiveDate set to the day it took effect. Quote effectiveDate when carriedOver is true. A date whose rate NBG has not published yet returns an error, never a guess. When nbgQuantity is not 1, state NBG's quoted form first, nbgRate GEL per nbgQuantity units (for example 1.6452 GEL per 100 JPY), and the per-unit rate beside it: that quoted form is what nbg.gov.ge and accounting software show.

{
  "type": "object",
  "properties": {
    "date": {
      "description": "Calendar date YYYY-MM-DD. Defaults to today in Tbilisi. Tomorrow's rate exists after about 17:00 Tbilisi time.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "currencies": {
      "description": "ISO 4217 codes to return, case-insensitive, duplicates ignored (for example [\"USD\", \"EUR\"]). Omit for all currencies. GEL has no row, since every rate is in GEL, so it is listed in unknownCodes.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 64
      }
    },
    "language": {
      "type": "string",
      "enum": [
        "en",
        "ka"
      ],
      "description": "Language of currency names: en (default) or ka (Georgian). Codes, numbers and dates are identical in both."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "requestedDate": {
      "type": "string"
    },
    "effectiveDate": {
      "type": "string",
      "description": "Calendar date the returned rate took effect, as published by NBG"
    },
    "carriedOver": {
      "type": "boolean",
      "description": "true when the rate in force on requestedDate took effect on an earlier day; it is still the official rate"
    },
    "rates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "rate": {
            "type": "number",
            "description": "GEL per ONE unit of the currency"
          },
          "diff": {
            "type": "number",
            "description": "Change versus the previous published rate, per one unit; values below 0.000001 use exponent notation, such as 4e-7"
          },
          "nbgQuantity": {
            "type": "number",
            "description": "Units NBG quotes the raw rate for (1, 10, 100, 1000 or 10000)"
          },
          "nbgRate": {
            "type": "number",
            "description": "Raw rate as published by NBG, for nbgQuantity units"
          }
        },
        "required": [
          "code",
          "name",
          "rate",
          "diff",
          "nbgQuantity",
          "nbgRate"
        ],
        "additionalProperties": false
      }
    },
    "unknownCodes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "requestedDate",
    "effectiveDate",
    "carriedOver",
    "rates",
    "unknownCodes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Converts an amount between two currencies using the official NBG rate in force on a calendar date. Either side may be GEL; a pair without GEL is converted through GEL (via: "GEL"). Show resultRounded as the amount; result is the unrounded value for further calculation. Dates are calendar days in Tbilisi; the default is today. NBG sets a rate on business days around 17:00 Tbilisi time, valid from the next calendar day until the next rate, so after 17:00 tomorrow can be requested by date. Sundays, Mondays and days after a public holiday have no rate of their own: the rate in force was set earlier and is returned with carriedOver true and effectiveDate set to the day it took effect. Quote effectiveDate when carriedOver is true. A date whose rate NBG has not published yet returns an error, never a guess.

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "description": "Amount in the \"from\" currency. May be negative."
    },
    "from": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "ISO 4217 code, or GEL."
    },
    "to": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "ISO 4217 code, or GEL."
    },
    "date": {
      "description": "Calendar date YYYY-MM-DD whose official rate to apply. Defaults to today in Tbilisi.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    }
  },
  "required": [
    "amount",
    "from",
    "to"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number"
    },
    "from": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "result": {
      "type": "number",
      "description": "Unrounded"
    },
    "resultRounded": {
      "type": "number",
      "description": "result rounded half up to 2 decimals from the exact value; the amount to show. JSON drops trailing zeros, so 3.90 arrives as 3.9. Exact up to about 7e13 in the target currency; above that the nearest double."
    },
    "rate": {
      "type": "number",
      "description": "One unit of \"from\" expressed in \"to\""
    },
    "via": {
      "type": "string",
      "enum": [
        "direct",
        "GEL"
      ]
    },
    "requestedDate": {
      "type": "string"
    },
    "effectiveDate": {
      "type": "string",
      "description": "Calendar date the returned rate took effect, as published by NBG"
    },
    "carriedOver": {
      "type": "boolean",
      "description": "true when the rate in force on requestedDate took effect on an earlier day; it is still the official rate"
    }
  },
  "required": [
    "amount",
    "from",
    "to",
    "result",
    "resultRounded",
    "rate",
    "via",
    "requestedDate",
    "effectiveDate",
    "carriedOver"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Converts a list of amounts, each at the official NBG rate in force on its own date: one call for a list of invoices. Items are answered independently; a bad date or code fails only its item, with the error text in that item. total is present when every converted item has the same target currency and covers the converted items only; call it partial when skipped is not 0. Once NBG stops answering, the remaining dates fail with the same error without being asked. Show resultRounded as the amount; result is the unrounded value for further calculation. Dates are calendar days in Tbilisi; the default is today. NBG sets a rate on business days around 17:00 Tbilisi time, valid from the next calendar day until the next rate, so after 17:00 tomorrow can be requested by date. Sundays, Mondays and days after a public holiday have no rate of their own: the rate in force was set earlier and is returned with carriedOver true and effectiveDate set to the day it took effect. Quote effectiveDate when carriedOver is true. A date whose rate NBG has not published yet returns an error, never a guess.

{
  "type": "object",
  "properties": {
    "items": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number",
            "description": "Amount in the \"from\" currency. May be negative."
          },
          "from": {
            "type": "string",
            "maxLength": 64,
            "description": "ISO 4217 code, or GEL."
          },
          "to": {
            "type": "string",
            "maxLength": 64,
            "description": "ISO 4217 code, or GEL."
          },
          "date": {
            "description": "Calendar date YYYY-MM-DD whose official rate to apply. Defaults to today in Tbilisi.",
            "type": "string",
            "maxLength": 64
          }
        },
        "required": [
          "amount",
          "from",
          "to"
        ]
      },
      "description": "1 to 100 conversions, each with the fields of nbg_convert; items are answered independently."
    }
  },
  "required": [
    "items"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "amount": {
                "type": "number"
              },
              "from": {
                "type": "string"
              },
              "to": {
                "type": "string"
              },
              "result": {
                "type": "number",
                "description": "Unrounded"
              },
              "resultRounded": {
                "type": "number",
                "description": "result rounded half up to 2 decimals from the exact value; the amount to show. JSON drops trailing zeros, so 3.90 arrives as 3.9. Exact up to about 7e13 in the target currency; above that the nearest double."
              },
              "rate": {
                "type": "number",
                "description": "One unit of \"from\" expressed in \"to\""
              },
              "via": {
                "type": "string",
                "enum": [
                  "direct",
                  "GEL"
                ]
              },
              "requestedDate": {
                "type": "string"
              },
              "effectiveDate": {
                "type": "string",
                "description": "Calendar date the returned rate took effect, as published by NBG"
              },
              "carriedOver": {
                "type": "boolean",
                "description": "true when the rate in force on requestedDate took effect on an earlier day; it is still the official rate"
              }
            },
            "required": [
              "amount",
              "from",
              "to",
              "result",
              "resultRounded",
              "rate",
              "via",
              "requestedDate",
              "effectiveDate",
              "carriedOver"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "amount": {
                "type": "number"
              },
              "from": {
                "type": "string"
              },
              "to": {
                "type": "string"
              },
              "date": {
                "type": "string"
              },
              "error": {
                "type": "string",
                "description": "Why this item was not converted; the same text nbg_convert would return"
              }
            },
            "required": [
              "amount",
              "from",
              "to",
              "error"
            ],
            "additionalProperties": false
          }
        ]
      },
      "description": "One entry per input item, in input order: a conversion, or the item with an error"
    },
    "converted": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "skipped": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "total": {
      "description": "Present only when at least one item converted, every converted item has the same target currency, and the sum is a finite number. It covers the converted items only: when skipped is not 0, say the total is partial and list the skipped items.",
      "type": "object",
      "properties": {
        "to": {
          "type": "string"
        },
        "resultRounded": {
          "type": "number",
          "description": "Exact sum of the resultRounded values of the converted items, as a ledger posts lines"
        }
      },
      "required": [
        "to",
        "resultRounded"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "items",
    "converted",
    "skipped"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Lists every currency NBG publishes a GEL rate for today, with its name and the unit quantity NBG quotes it in. NBG quoted other currencies in the past, so a code missing here may still have historical rates. nbgQuantity is the unit count NBG quotes the raw rate for (JPY is quoted as 1.6452 GEL per 100 JPY); for the rates themselves call nbg_get_rates.

{
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "enum": [
        "en",
        "ka"
      ],
      "description": "Language of currency names: en (default) or ka (Georgian). Codes, numbers and dates are identical in both."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "effectiveDate": {
      "type": "string",
      "description": "Calendar date the returned rate took effect, as published by NBG"
    },
    "currencies": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "nbgQuantity": {
            "type": "number"
          }
        },
        "required": [
          "code",
          "name",
          "nbgQuantity"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "effectiveDate",
    "currencies"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Official NBG rate of one currency (GEL per one unit) in force on every calendar day of an inclusive range of at most 366 days. Dates are calendar days in Tbilisi. Days without a rate of their own (Sundays, Mondays and days after a public holiday; before September 2021 NBG set a rate for every calendar day) carry the earlier rate. Days whose own rate is in force contain only date and rate; a carried-over day adds effectiveDate and carriedOver: true. Quote effectiveDate when carriedOver is true. A range reaching a date NBG has not published yet returns an error. summary holds the first, last, change, lowest and highest rate with their dates, and the average over the calendar days, computed by the server: report those rather than deriving them. One NBG request per call.

{
  "type": "object",
  "properties": {
    "currency": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "ISO 4217 code, for example USD."
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First calendar day, inclusive."
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last calendar day, inclusive. At most 366 days including \"from\"."
    }
  },
  "required": [
    "currency",
    "from",
    "to"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "currency": {
      "type": "string"
    },
    "from": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "days": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          },
          "rate": {
            "type": "number",
            "description": "GEL per ONE unit of the currency"
          },
          "effectiveDate": {
            "type": "string",
            "description": "Present only on carried-over days: the calendar date the rate took effect. When absent, the rate took effect on date."
          },
          "carriedOver": {
            "type": "boolean",
            "const": true,
            "description": "Present, and true, only on days that carry a rate set earlier"
          }
        },
        "required": [
          "date",
          "rate"
        ],
        "additionalProperties": false
      }
    },
    "summary": {
      "type": "object",
      "properties": {
        "first": {
          "type": "number",
          "description": "Rate on from"
        },
        "last": {
          "type": "number",
          "description": "Rate on to"
        },
        "change": {
          "type": "number",
          "description": "last minus first, exact, at the decimals NBG's quantity gives the currency"
        },
        "min": {
          "type": "number"
        },
        "minDate": {
          "type": "string",
          "description": "First calendar day the minimum occurs on"
        },
        "max": {
          "type": "number"
        },
        "maxDate": {
          "type": "string",
          "description": "First calendar day the maximum occurs on"
        },
        "average": {
          "type": "number",
          "description": "Arithmetic mean over every calendar day of the range, carried-over days included"
        }
      },
      "required": [
        "first",
        "last",
        "change",
        "min",
        "minDate",
        "max",
        "maxDate",
        "average"
      ],
      "additionalProperties": false,
      "description": "Computed by the server; report these instead of deriving them from days. change and average are exact, rounded half up to the decimals NBG's quantity gives the currency, 4 + log10(nbgQuantity), the largest over the days (4 for USD, 7 for AMD)."
    }
  },
  "required": [
    "currency",
    "from",
    "to",
    "days",
    "summary"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}