openapi: 3.0.0
info:
  title: Greenly Carbon Analytics alternatives transactions API
  version: '1.5'
  description: "# Introduction\nThe Greenly Carbon Analytics API is a set of RESTful services which enable the enrichment of bank transactions with carbon footprint analytics.\n\n All request and response payloads, including errors, use the JSON naming convention.\n\n2 API environments are available: a sandbox environment used to test the API capacities and your integration with these services and the production environment.\n\nTo have access to these environments, you will need to obtain API keys by contacting us at contact@greenly.earth.\n\nThe 2 environments are available at the following URL:\n - Sandbox environment: <https://apisandbox.greenly.earth/v1.5>\n - Production environment: <https://api.greenly.earth/v1.5>\n# Getting Started\nYou can download our sample Postman requests at the following URL: <http://offspend.github.io/PostmanRequests.zip>\n\nYou then need to add your API key in the Greenly Sandbox API environment. After that, you should be able to create a user. Executing this Postman request will automatically set the latest created userId as a global env in your Postman environment. So after creating this user, you can directly try all the other requests including the Calculate Carbon Footprints one which will show you the carbon footprint analysis for a lot of different transactions.\n# Input Transaction Labels\nThe algorithm classifies transactions to providers and purchase categories so as to measure their carbon footprint based on their labels. In the best case, this label would consist only of the name of the recipient of the payment. Yet, in general, raw label contain overhead information, related in particular to the type of payment and the date of the transaction.\n\nIn the case where a cleaning of the overhead is done on the bank side, only the cleaned label should be transmitted to the API. If no cleaning is done or the cleaning is deemed to be too noisy or unreliable, raw labels can be also transmitted to the API. \n\nIndeed, when a label is received, the classification algorithm looks for all common overhead patterns, such as  “CB XXXXX”, “paiement par carte”, or “01/06/2020”, among many other overhead patterns.The classification algorithm removes all such patterns used by all banks that it was possible to enumerate during the R&D process. Yet, it is always possible that some patterns could not be found, or that the format evolves at some time. In that case, the cleaning of the pattern should either be done at the user side, or the user should contact the Greenly support team to ensure proper cleaning of the raw label and hence proper classification and estimation of the carbon footprint.\n\nAs a toy example, let us consider the following raw label to illustrate the allowed format: “paiement par carte super u 35 st jacques de 05/07”. Providing the “cleaned label” would be “super u 35 st jacques de“ or variations thereof, and as it can be observed the cleaned label does not need to be perfectly informative nor cleaned. As mentioned above, it is also possible to simply provide the raw label and the API will take care of removing the date and the overhead linked to card payment. Yet, it is not desired to provide both cleaned and raw labels using a separator (e.g. a new line ‘\n’ separator or other variations) as this would lead to degraded performances.\n\n# Authentication\n\n<!-- ReDoc-Inject: <security-definitions> -->"
  contact:
    email: contact@greenly.earth
servers:
- url: https://api.greenly.earth/v1.5
tags:
- name: transactions
paths:
  /transactions/calculateCarbonFootprints:
    post:
      operationId: CalculateCarbonFootprints
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/CalculateCarbonFootprintsOutput'
                - {}
        '401':
          description: Authentication Failed
        '404':
          description: User not found
        '422':
          description: Input request body does not have the right format
        '500':
          description: An unexpected error occured while processing the request
      description: Calculate the carbon footprints of the input transactions
      summary: Calculate carbon footprints
      tags:
      - transactions
      security: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateCarbonFootprintsArgs'
components:
  schemas:
    Translations:
      $ref: '#/components/schemas/Record_Language.string_'
    Translation:
      properties:
        de:
          type: string
        sv:
          type: string
        es:
          type: string
        it:
          type: string
        en:
          type: string
        fr:
          type: string
      type: object
    Opaque_AlternativeId.string_:
      allOf:
      - type: string
      - properties:
          __TYPE__:
            type: string
            enum:
            - AlternativeId
            nullable: false
        required:
        - __TYPE__
        type: object
    Pick_Transaction.tagValues_:
      properties:
        tagValues:
          items:
            $ref: '#/components/schemas/TagValue'
          type: array
          description: Set of tag values applied to the transaction. These have an influence on carbon footprint calculation.
      required:
      - tagValues
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    RecommendedProviderOutput:
      properties:
        logoUrl:
          type: string
          nullable: true
          description: Url of the provider's logo stored in svg format.
        url:
          type: string
          nullable: true
          description: Url of the recommended provider.
        name:
          type: string
          description: Name of the recommended provider.
      required:
      - logoUrl
      - url
      - name
      type: object
    CarbonFootprintOutput:
      allOf:
      - $ref: '#/components/schemas/Pick_Transaction.tagValues_'
      - properties:
          cleanedLabel:
            type: string
            description: 'Cleaned label for the transaction. If a specific provider / brand has been

              identified in the transaction label, it will be the name of this provider / brand.

              It might be the same as the input label if no cleaning operations were carried out.'
          alternatives:
            items:
              $ref: '#/components/schemas/AlternativeOutput'
            type: array
            description: 'Populated list of the low-carbon alternatives that are recommended for this particular transaction.

              Optional feature.'
          alternativeIds:
            items:
              $ref: '#/components/schemas/AlternativeId'
            type: array
            description: 'List of the ids of the low-carbon alternatives that are recommended for this particular transaction.

              Optional feature.'
          purchaseCategoryId:
            type: string
            description: 'Id of the category of the transaction (e.g. TELECOM, SUPERMARKET, AUTOBUS).

              The relevant associated information can

              be found in the purchase categories endpoint.'
          isGreen:
            type: boolean
            description: 'Boolean value to indicate whether the transaction is associated with a positive action, i.e., an action

              that has a carbon footprint that is lower than the conventional behavour. This means that the transaction

              has generated a positive amount of avoided CO2eq.'
          transactionId:
            type: string
            description: References the id of the transaction whose carbon footprint it is.
          carbonFootprintEquivalents:
            $ref: '#/components/schemas/CarbonFootprintEquivalents'
          methodology:
            allOf:
            - $ref: '#/components/schemas/Translation'
            nullable: true
            description: 'Methodology of the carbon footprint calculation

              Optional feature.'
          carbonFootprint:
            allOf:
            - $ref: '#/components/schemas/Pick_CarbonFootprint.emissionsInKg-or-avoidedEmissionsInKg_'
            nullable: true
            description: 'Represents the carbon footprint of a transaction.

              It can be null in the following cases:

              - The transaction could not be categorized

              - The transaction has a positive amount in euros and represents revenues

              - The transaction type is not compatible with carbon footprint analysis'
        required:
        - cleanedLabel
        - purchaseCategoryId
        - isGreen
        - transactionId
        - carbonFootprintEquivalents
        - carbonFootprint
        type: object
    CalculateCarbonFootprintsOutput:
      items:
        $ref: '#/components/schemas/CarbonFootprintOutput'
      type: array
    InputTransaction:
      properties:
        countryCode:
          type: string
          description: "(Optional) A country-code in the ISO 3166-1 alpha-2 format (see list below). In the absence of a country-code\n  the default country code if 'FR'.\nAustria:\tAT\nBelgium:\tBE\nBulgaria:\tBG\nCroatia:\tHR\nCyprus:\tCY\nCzech Republic:\tCZ\nDenmark:\tDK\nEstonia:\tEE\nFinland\tFI\nFrance:\tFR\nGermany:\tDE\nGreece:\tGR\nHungary:\tHU\nIreland, Republic of (EIRE):\tIE\nItaly:\tIT\nLatvia:\tLV\nLithuania: LT\nLuxembourg:\tLU\nMalta:\tMT\nNetherlands:\tNL\nNorway: NO\nPoland:\tPL\nPortugal:\tPT\nRomania:\tRO\nSlovakia:\tSK\nSlovenia:\tSI\nSpain:\tES\nSweden:\tSE\nSwitzerland: CH\nUnited Kingdom:\tGB"
        tagValues:
          items:
            $ref: '#/components/schemas/TagValue'
          type: array
          description: '(Optional) Additional tag values to be applied to the transaction carbon footprint calculation (e.g. ORGANIC for restaurant or supermarket).

            Available tag values per purchase category can be retrieved in the purchase categories endpoint.'
        purchaseCategoryId:
          type: string
          description: '(Optional) PurchaseCategory''s id to bypass the purchase category estimated from the label. The emission coefficient of the input purchase

            category is then used to calculate the carbon footprint (possibly modified by input tagValues), instead of the predicted one.

            The possible purchaseCategory''s ids can be obtained using the purchaseCategories endpoint.


            It is also possible to input a higher level, less precise purchase category (so-called parentPurchase category). The possible parent purchase

            categories are :

            - ''TRANSPORT''

            - ''FOOD''

            - ''SHOPPING''

            - ''SERVICES''

            - ''HOUSING''


            The mapping between the purchase categories and the parent purchase categories can be also found in the purchaseCategories endpoint.'
        mccCode:
          type: string
          description: (Optional) MCC Code (following ISO 18245) which serves as fallback in case the categorization based on the label failed.
        amount:
          type: number
          format: double
          description: 'Amount of the transaction.

            Amount is positive for revenues and negative for purchases.'
        type:
          $ref: '#/components/schemas/TransactionType'
          description: 'The type of the transaction.

            Only the types POINT_OF_SALE, CASH, TRANSFER, DIRECT_DEBIT, DEBIT lead the transaction to be analysed for carbon footprints.'
        label:
          type: string
          description: Transaction raw label.
        amountInEur:
          type: number
          format: double
          description: 'Amount in euros of the transaction.

            Amount is positive for revenues and negative for purchases.'
        id:
          type: string
          description: 'Id of the transaction.

            The transaction will be referenced with this id in

            linked ouputs (such as carbon footprint objects)'
      required:
      - type
      - label
      - id
      type: object
      description: 'Represents a transaction which can be either a bank transaction

        or a cash transaction'
    AlternativeId:
      $ref: '#/components/schemas/Opaque_AlternativeId.string_'
    AlternativeDescriptionTranslations:
      $ref: '#/components/schemas/Translations'
      description: 'Very short intuitive description of the suggested low-carbon advice or provider

        (tweet format with less than 280 characters) in our multilingual format.'
    Language:
      enum:
      - en
      - fr
      - es
      - it
      - sv
      - de
      type: string
    AlternativeOutput:
      properties:
        recommendedProviders:
          items:
            $ref: '#/components/schemas/RecommendedProviderOutput'
          type: array
          description: List of alternative providers
        ratioEstimatedReduction:
          type: number
          format: double
          nullable: true
          description: 'Estimated average reduction resulting from the suggested low-carbon alternative. Hence a ratio of 0.66 means a reduction

            of 66%, i.e., that the carbon footprint is divided by 3.'
        sources:
          items:
            type: string
          type: array
          nullable: true
          description: A list of url. Can be null.
        description:
          $ref: '#/components/schemas/AlternativeDescriptionTranslations'
        geographicalRestriction:
          allOf:
          - $ref: '#/components/schemas/CountryId'
          nullable: true
          description: 'If specified, it means the alternative is valid only for the specified country.

            If null, then the alternative is valid everywhere.'
        isProviderAlternative:
          type: boolean
          description: 'boolean to indicate whether the alternative is a general advice/behaviour alternative or is related to

            a specific alternative provider.'
        id:
          type: string
          description: UUID4 unique identifier of the alternative
      required:
      - recommendedProviders
      - ratioEstimatedReduction
      - sources
      - description
      - geographicalRestriction
      - isProviderAlternative
      - id
      type: object
    CountryId:
      enum:
      - GB
      - FR
      - ES
      - IT
      - SE
      - DE
      type: string
    CarbonFootprintEquivalents:
      properties:
        avoidedEmissionsInKgEquivalent:
          allOf:
          - $ref: '#/components/schemas/Translation'
          nullable: true
          description: intuitive equivalent for the avoided CO2e emissions
        emissionsInKgEquivalent:
          allOf:
          - $ref: '#/components/schemas/Translation'
          nullable: true
          description: intuitive equivalent for the emitted CO2e emissions
      required:
      - avoidedEmissionsInKgEquivalent
      - emissionsInKgEquivalent
      type: object
      description: Intuitive illustration of the calculated carbon footprint in terms of day to day actions and objects
    Pick_CarbonFootprint.emissionsInKg-or-avoidedEmissionsInKg_:
      properties:
        emissionsInKg:
          type: number
          format: double
          description: Emissions generated in kg of CO2 equivalent (all greenhouse gas are converted to CO2).
        avoidedEmissionsInKg:
          type: number
          format: double
          description: 'Emissions avoided in kg of CO2 equivalent (all greenhouse gas are converted to CO2).

            Emissions avoided are calculated in regard to a reference situation that can be found

            in the methodology (e.g. carsharing vs driving solo in your car)'
      required:
      - emissionsInKg
      - avoidedEmissionsInKg
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    Record_Language.string_:
      properties:
        en:
          type: string
        fr:
          type: string
        es:
          type: string
        it:
          type: string
        sv:
          type: string
        de:
          type: string
      type: object
      description: Construct a type with a set of properties K of type T
    TagValue:
      properties:
        value:
          anyOf:
          - type: string
          - type: number
            format: double
          - type: boolean
        tagId:
          type: string
      required:
      - value
      - tagId
      type: object
    CalculateCarbonFootprintsArgs:
      properties:
        languages:
          items:
            $ref: '#/components/schemas/Language'
          type: array
          description: 'languages requested for the methodologies.

            If no language is provided we use a default language based on the countryId of the transaction.'
        transactions:
          items:
            $ref: '#/components/schemas/InputTransaction'
          type: array
          description: List of the user transactions.
        userId:
          type: string
          description: Id of the user owning the transactions.
      required:
      - transactions
      type: object
    TransactionType:
      description: 'The input type is type of the bank transaction and can take any of the following values:

        * CREDIT: Default type when it is not possible to determine the type of a revenue entry.

        * DEBIT: Default type when it is not possible to determine the type of a disbursement of money.

        * DINTEREST: Interest on a bank account.

        * DIVIDEND: Payment of a company to its shareholders.

        * BANK_FEE: Fees on a bank account.

        * DEPOSIT: Deposit of money in an agency.

        * ATM: Withdrawing money from an ATM.

        * POINT_OF_SALE: Payment with a credit card.

        * CREDIT_CARD_PAYMENT: Month-end debit on a deferred card.

        * INTERNAL_TRANSFER: Transfer of money between two bank accounts of the same customer.

        * TRANSFER: Transfer of money between two bank accounts of two different customers.

        * CHECK: Transaction made by check.

        * CASH: Transaction carried out using a physical currency (notes and coins).

        * DIRECT_DEPOSIT: Deposit of money made by a payer directly into the payee''s bank account.

        * DIRECT_DEBIT: Transaction in which one person (or company) withdraws funds from another person''s bank account.

        * OTHER: When a transaction does not correspond to any of these types.


        Only the types POINT_OF_SALE, TRANSFER, DIRECT_DEBIT, DEBIT leads the transaction to be analyzed for carbon footprint.'
      enum:
      - CREDIT
      - DEBIT
      - INTEREST
      - DIVIDEND
      - BANK_FEE
      - DEPOSIT
      - ATM
      - POINT_OF_SALE
      - CREDIT_CARD_PAYMENT
      - INTERNAL_TRANSFER
      - TRANSFER
      - CHECK
      - CASH
      - DIRECT_DEPOSIT
      - DIRECT_DEBIT
      - OTHER
      type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: api-key
      in: header