markets.yaml

openapi: "3.0.0"
info:
  version: 1.0.3
  title: Sentifi Intelligence
  description: |
    Sentifi Intelligence API
    
servers:
  - url: https://apis.sentifi.com/v1.1/intelligence/markets
  - url: https://apis.sentifi.com/v1/oauth
    description: url for getting authorization token
paths:
  '/token':
    post:
      summary: get authorization token
      description: |
        * Use the endpoint: **https://apis.sentifi.com/v1/oauth/token**
        * You need to use this api to retrieve the `access_token`
        * After getting the `access_token`, the following api need to include in the request *headers*
          * Authorization: Bearer {access_token}
      parameters:
        - name: Authorization
          in: header
          description: |
            base64 encode of client id and client secret in the format `client_id:client_secret`
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum: ['password']
                username:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  scope:
                    type: string
                  organization:
                    type: string
                  access_token:
                    type: string
                  token_type:
                    type: string
                    enum: ['bearer']
                  expired_in:
                    type: number
                    format: int64
  '/top-theme':
    get:
      summary: List of top themes sorted by attention
      x-files:
        - https://drive.google.com/uc?export=view&id=1EL4ssvL_ExFNomNXR8hp1EuIKPQuBA5h&__type=.png
        - https://drive.google.com/uc?export=view&id=1JEnEwv-YMI98FqjBoWWDN_3G0sVfnUGM&__type=.png
        
      description: |-
        Depending on filters, this API will return list of top x themes sorted by attention
      
        More information can be found here:
        
        https://sentifi.atlassian.net/wiki/spaces/MARK/pages/327221260/Themes+Product+Requirements
      parameters:
        - name: size
          in: query
          description: number of results
          schema:
            type: number
            default: 10
        - $ref: '#/components/parameters/dateStart'
        - $ref: '#/components/parameters/dateEnd'
        - name: country-codes
          in: query
          description: |-
            List of comma separated ISO alpha 2 country codes
            
            https://www.nationsonline.org/oneworld/country_code_list.htm
          required: false
          schema:
            type: string
        - name: industry-ids
          in: query
          description: List of comma separated industry IDs
          required: false
          schema:
            type: number
            format: int64
        - name: sector-ids
          in: query
          description: List of comma separated sector IDs
          required: false
          schema:
            type: number
            format: int64
        - name: region-ids
          in: query
          description: List of comma separated region IDs
          required: false
          schema:
            type: number
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
               allOf: 
                 - $ref: '#/components/schemas/ApiResponseSuccess'
                 - type: object
                   properties:
                     data:
                        type: object
                        properties:
                          themeInfo:
                            $ref: '#/components/schemas/ThemeInfo'
                          attention: 
                            type: number
                            format: float
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
  '/asset/insight/region':
    get:
      summary: Get a list of regions and corresponding asset allocation shift and sentiment data
      description: |-
        - This API returns a list of regions for a specific time frame that we selected. For each region, there will be corresponding data regarding sentiment score, sentiment label, sentiment change, asset allocation shift and shift change for the time period selected
        
          The time period selected should be full month(s), for example: lastmonth, last2months, last3months
          
          More information can be found here:
          
          https://docs.google.com/document/d/1aSwjxKnjLsRH1Decw--BRSaEbK7iY0Zwt79aQvfF2fQ/edit
        
      parameters:
        - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf: 
                  - $ref: '#/components/schemas/ApiResponseSuccess'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            regionInfo:
                              type: object
                              properties:
                                id:
                                  type: number
                                  format: int
                                  example: 1
                                name:
                                  type: string
                                  example: "Asia Developed"
                            shift:
                              $ref: '#/components/schemas/Shift'
                            sentiment:
                              $ref: '#/components/schemas/Sentiment'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
  '/asset/insight/marketcap':
    get:
      summary: Get a list of market cap groups and corresponding asset allocation shift data
      description: |-
        - This API returns a list of market cap groups and corresponding asset allocation shift data for a specific time frame that we selected.
        
          The time period selected should be full month(s), for example: lastmonth, last2months, last3months
          
          More information can be found here:
          
          https://docs.google.com/document/d/1aSwjxKnjLsRH1Decw--BRSaEbK7iY0Zwt79aQvfF2fQ/edit
        
      parameters:
        - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf: 
                  - $ref: '#/components/schemas/ApiResponseSuccess'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            marketCapLabel:
                              type: object
                              properties:
                                id:
                                  type: string
                                  example: "small"
                                name:
                                  type: string
                                  example: "Asia Developed"
                            shift:
                              $ref: '#/components/schemas/Shift'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
  '/asset/insight/investor-type':
    get:
      summary: Get asset allocation shift and sentiment score for each investor type
      description: |-
        The API will return asset allocation shift and sentiment score for each investor type within selected sector(s)
          
          More information can be found here:
          
          https://docs.google.com/document/d/1aSwjxKnjLsRH1Decw--BRSaEbK7iY0Zwt79aQvfF2fQ/edit
      parameters:
        - name: sector-ids
          in: query
          description: one or a list of sector ids separated by `,`
          schema:
            type: number
            format: int64
          required: true
        - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
               allOf: 
                  - $ref: '#/components/schemas/ApiResponseSuccess'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            sectorInfo:
                              type: object
                              properties:
                                id:
                                  type: number
                                  format: int
                                  example: 1401
                                name:
                                  type: string
                                  example: "Consumer Cyclical"
                            investorTypes:
                              type: array
                              items:
                                type: object
                                properties:
                                  investorTypeInfo:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                        example: MF
                                      name:
                                        type: string
                                        example: Mutual Fund Manager
                                  shift:
                                    $ref: '#/components/schemas/Shift'
                                  sentiment:
                                    $ref: '#/components/schemas/Sentiment'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
  '/asset/stock/trend': 
    get:
      summary: Get stocks with the largest positive or negative asset allocation change
      description: |-
        This API gets stocks with the largest positive and negative asset allocation change and corresponding asset allocation shift and sentiment change
          
          More information can be found here:
          
          https://docs.google.com/document/d/1aSwjxKnjLsRH1Decw--BRSaEbK7iY0Zwt79aQvfF2fQ/edit
      parameters:
        - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf: 
                  - $ref: '#/components/schemas/ApiResponseSuccess'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            inflows:
                              type: array
                              items:
                                type: object
                                properties:
                                  stockInfo:
                                    $ref: '#/components/schemas/stockInfo'
                                  sectorInfo:
                                    $ref: '#/components/schemas/sectorInfo'
                                  shift:
                                    $ref: '#/components/schemas/Shift'
                                  sentiment:
                                    $ref: '#/components/schemas/Sentiment'
                            outflows:
                              type: array
                              items:
                                type: object
                                properties:
                                  stockInfo:
                                    $ref: '#/components/schemas/stockInfo'
                                  sectorInfo:
                                    $ref: '#/components/schemas/sectorInfo'
                                  shift:
                                    $ref: '#/components/schemas/Shift'
                                  sentiment:
                                    $ref: '#/components/schemas/Sentiment'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
  '/sentiment/topic':
    get:
      summary: Get time series of daily sentiment or sentiment simple moving average for a list of companies, currencies, commodities, countries over a specified time frame
      parameters:
        - name: topic-ids
          in: query
          description: a list of topic ids separated by `,`
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/movingAvarage'
        - $ref: '#/components/parameters/dateStart'
        - $ref: '#/components/parameters/dateEnd'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf: 
                  - $ref: '#/components/schemas/ApiResponseSuccess'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            sentiments:
                              type: array
                              items:
                                $ref: '#/components/schemas/Score'
                            info: 
                              type: object
                              properties:
                                id:
                                  type: number
                                name:
                                  type: string
security: 
  - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    Sentiment:
      type: object
      properties:
        value:
          type: number
          format: float
          example: 57
        label:
          type: string
          enum: ["positive", "negative", "neutral"]
        valueChange:
          type: number
          format: int64
          example: -3
          
    Shift:
      type: object
      properties:
        value:
          type: number
          format: float
          example: 0.062
        valueChange:
          type: number
          format: int64
          example: 0.00631
    
    ThemeInfo:
      type: object
      properties:
        id:
          type: number
          format: int64
          example: 85
        name:
          type: string
          example: 'Clean Tech'

    ApiResponseSuccess:
      type: object
      properties:
        data:
          type: object
        extra:
          type: object
          properties:
            updatedTime:
              type: string
              format: date-time
              
    Score:
      type: object
      properties:
        date:
          type: string
          format: date-time
        value:
          type: number
          format: float
        label:
          type: string
          enum: ["positive", "negative", "neutral"]
        
    AssetAllocationApiResponseError:
      type: object
      properties:
        code:
          type: number
          format: int64
          example: 400
        status:
          type: string
          example: "Bad Request"
        message:
          type: string
          example: "Failed to process request due to invalid method call. Please see details in error message."
        errors:
          type: array
          items:
            type: string
            example: "Unsupported value: 1year"
            
    EventApiResponseError:
      type: object
      properties:
        code:
          type: number
          format: int64
          example: 500
        status:
          type: string
          example: "Internal Server Error"
        message:
          type: string
          example: "Failed to process request due to unexpected error"
        errors:
          type: array
          items:
            type: string
            example: "Required List parameter 'event-ids' is not present"
            
    stockInfo:
      type: object
      properties:
        id:
          type: number
          format: int64
          example: 1831982
        name:
          type: string
          example: "Makpetrol AD"
        ticker:
           type: string
           example: "MPT"
           
    ApiResponseError:
      type: object
      properties:
        extra:
          type: object
          properties:
            updatedTime:
              type: string
              format: date-time
            errorCode:
              type: integer
            errorMessage:
              type: string
           
    sectorInfo:
      type: object
      properties:
        id:
          type: number
          example: 1403
        name:
          type: string
          example: "Energy"
  parameters:
    timeframe:
      in: query
      name: timeframe
      description: >-
        data's timeframe in previous x day(s). Following the requirement in ticket [INSNEW-6](https://sentifi.atlassian.net/browse/INSNEW-6)
      schema:
        type: integer
        enum: 
          - 1
          - 7
          - 30
          - 90 # 3 months
          - 180 # 9 months
          - 365 # 1 years
          - 730 # 2 years
          - 1095 #3 years
    timeSeriesFormat:
      in: query
      name: tsf
      schema:
        type: string
        enum: ['series', 'endpoints']
        default: endpoints
      description: >-
        timebased data list return from the api can be retreived as series or 2 endpoints (start & end).
        Eg. when timeframe is 7day, with SERIES format it would return 7 data points, with ENDPOINTS it would return 2 data points (recent and last 7day data point).
    language:
      in: query
      name: lang
      schema:
        type: string
        enum: ['en', 'de']
        default: 'en'
    dateStart:
      in: query
      name: start-date
      schema:
        type: string
      description: date value in format `YYYY-MM-DD`
      required: true
    movingAvarage:
      in: query
      name: moving-average
      schema:
        type: number
      description: | 
        If we don't set this param, the default moving average would be used as
        
        * For a time period of < 5 = default SMA for price: 1
        * For a time period of ≥ one week, < 1 month = default SMA for price: 5
        * For a time period of ≥ 1 month, < 2 month = default SMA for price: 20
        * For a time period of ≥ 2 month = default SMA for price: 50
    dateEnd:
      in: query
      name: end-date
      schema:
        type: string
      description: date value in format `YYYY-MM-DD`
      required: true
    period:
      in: query
      name: period
      schema:
        type: string
      description: period of time (ex:lastmonth, last2months)
      required: true