openapi: 3.0.0
info:
  title: Greenly Carbon Analytics alternatives offsetProjects 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: offsetProjects
paths:
  /offsetProjects:
    get:
      operationId: GetOffsetProjects
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/OffsetProjectOutput'
                type: array
        '401':
          description: Authentication Failed
        '500':
          description: An unexpected error occured while processing the request
      description: Retrieve the details of all offset projects
      summary: Get all offset projects
      tags:
      - offsetProjects
      security: []
      parameters: []
  /offsetProjects/{offsetProjectId}:
    get:
      operationId: GetOffsetProject
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/OffsetProjectOutput'
                - {}
        '401':
          description: Authentication Failed
        '404':
          description: Resource not found
        '500':
          description: An unexpected error occured while processing the request
      description: Retrieve the details of one offset project.
      summary: Get offset project
      tags:
      - offsetProjects
      security: []
      parameters:
      - in: path
        name: offsetProjectId
        required: true
        schema:
          type: string
  /offsetProjects/bookOffsetQuantity:
    post:
      operationId: BookOffsetQuantity
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/BookOffsetOutput'
                - {}
        '401':
          description: Authentication Failed
        '422':
          description: Input request body does not have the right format
        '500':
          description: An unexpected error occured while processing the request
      description: Booking a quantity of CO2 equivalent to offset from an offset project
      summary: Book offset project
      tags:
      - offsetProjects
      security: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookOffsetArgs'
components:
  schemas:
    Translations:
      $ref: '#/components/schemas/Record_Language.string_'
    BookOffsetOutput:
      properties:
        totalPrice:
          type: number
          format: double
          description: Total price corresponding to the booking realized
        bookingSuccessful:
          type: boolean
          description: Boolean representing whether the booking was successfully done.
      required:
      - totalPrice
      - bookingSuccessful
      type: object
    BookOffsetArgs:
      properties:
        email:
          type: string
          description: (Optional) Email of the user carrying out the booking
        bookedOffsetInTCO2eq:
          type: number
          format: double
          description: Quantity of offsetting being booked (in TCO2eq)
        offsetProjectId:
          type: string
          description: Unique identifier of the chosen project
      required:
      - bookedOffsetInTCO2eq
      - offsetProjectId
      type: object
    OffsetProjectOutput:
      properties:
        remainingOffsetInTCO2eq:
          type: number
          format: double
          description: Remaining quantity of CO2 equivalent that is available for booking through the project (in tons of CO2 equivalents)
        totalOffsetInTCO2eq:
          type: number
          format: double
          description: Total quantity of CO2 equivalent that will be offset by the project (in tons of CO2 equivalents)
        priceInEuroPerTCO2eq:
          type: number
          format: double
          description: Price of the offsetting (in euro per ton of CO2 equivalent)
        certificationsLogoURL:
          items:
            type: string
          type: array
          description: List of the logos associated to the certification of the project
        certifications:
          items:
            type: string
          type: array
          description: List of the certifications of the project
        partnerLogoURL:
          type: string
          description: Logo of the company providing the project
        partner:
          type: string
          description: Name of the company providing the project
        longDescription:
          $ref: '#/components/schemas/Translations'
          description: Description of the project in a detailled paragraph with additional informations (in a multilingual format).
        shortHandDescription:
          $ref: '#/components/schemas/Translations'
          description: Description of the project in a few words (in a multilingual format).
        location:
          type: string
          description: Geographical localisation of the offsetting project
        name:
          type: string
          description: Name of the offset project
        id:
          type: string
          description: Unique identifier of the offset project
      required:
      - remainingOffsetInTCO2eq
      - totalOffsetInTCO2eq
      - priceInEuroPerTCO2eq
      - certificationsLogoURL
      - certifications
      - partnerLogoURL
      - partner
      - longDescription
      - shortHandDescription
      - location
      - name
      - id
      type: object
    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
  securitySchemes:
    api_key:
      type: apiKey
      name: api-key
      in: header