Object: ggStock

Overview

The ggStock object provides comprehensive data for a specific stock, including fundamental company information and time-series pricing data at 1-minute and 5-minute intervals. This object serves as the primary container for accessing both real-time and historical stock market data.

Data Structure

Each ggStock object represents a single stock with its associated market data and company fundamentals. The object includes:

Company identification (symbol, name, exchange)
Current market metrics (price, volume, market cap)
Financial ratios (P/E ratio, EPS, dividend yield)
Performance indicators (52-week high/low)
Historical OHLC (Open, High, Low, Close) data at multiple time intervals

Schema

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "CompanyStockProfile",
  "description": "A profile detailing a corporation's stock market presence, including historical market data structured as a dictionary with timestamps as keys.",
  "type": "object",
  "properties": {
    "symbol": {
      "description": "Corporation's stock ticker symbol.",
      "type": "string"
    },
    "companyName": {
      "description": "Registered corporation name.",
      "type": "string"
    },
    "exchange": {
      "description": "Stock exchange where the stock is listed.",
      "type": "string"
    },
    "industry": {
      "description": "Corporation's primary industry.",
      "type": "string"
    },
    "currentPrice": {
      "description": "Current stock trading price.",
      "type": "number",
      "minimum": 0
    },
    "marketCap": {
      "description": "Market value of outstanding shares.",
      "type": "number",
      "minimum": 0
    },
    "volume": {
      "description": "Volume of shares traded last session.",
      "type": "integer",
      "minimum": 0
    },
    "peRatio": {
      "description": "Price-to-Earnings ratio.",
      "type": "number"
    },
    "dividendYield": {
      "description": "Annual dividend yield percentage.",
      "type": "number",
      "minimum": 0
    },
    "eps": {
      "description": "Earnings Per Share.",
      "type": "number"
    },
    "week52High": {
      "description": "52-week highest trading price.",
      "type": "number",
      "minimum": 0
    },
    "week52Low": {
      "description": "52-week lowest trading price.",
      "type": "number",
      "minimum": 0
    },
    "historicalData": {
      "description": "Dictionary of historical market data, keyed by timestamps.",
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "oneMinute": {
            "description": "Data for the 1-minute candle.",
            "type": "object",
            "properties": {
              "open": {"type": "number"},
              "high": {"type": "number"},
              "low": {"type": "number"},
              "close": {"type": "number"},
              "volume": {"type": "integer", "minimum": 0}
            },
            "required": ["open", "high", "low", "close", "volume"]
          },
          "fiveMinute": {
            "description": "Optional data for the 5-minute candle.",
            "type": "object",
            "properties": {
              "open": {"type": "number"},
              "high": {"type": "number"},
              "low": {"type": "number"},
              "close": {"type": "number"},
              "volume": {"type": "integer", "minimum": 0}
            },
            "required": ["open", "high", "low", "close", "volume"]
          }
        },
        "required": ["oneMinute"]
      }
    }
  },
  "required": ["symbol", "companyName", "currentPrice", "historicalData"],
  "additionalProperties": false
}

YANG Schema

module company-stock-profile {
  namespace "http://example.com/company-stock-profile";
  prefix csp;

  organization "Example Organization";
  description "A profile detailing a corporation's stock market presence, including historical market data structured as a dictionary with timestamps as keys.";

  container companyStockProfile {
    leaf symbol {
      type string;
      description "Corporation's stock ticker symbol.";
    }

    leaf companyName {
      type string;
      description "Registered corporation name.";
    }

    leaf exchange {
      type string;
      description "Stock exchange where the stock is listed.";
    }

    leaf industry {
      type string;
      description "Corporation's primary industry.";
    }

    leaf currentPrice {
      type decimal64 {
        fraction-digits 2;
      }
      description "Current stock trading price.";
    }

    leaf marketCap {
      type decimal64 {
        fraction-digits 2;
      }
      description "Market value of outstanding shares.";
    }

    leaf volume {
      type uint64;
      description "Volume of shares traded last session.";
    }

    leaf peRatio {
      type decimal64 {
        fraction-digits 2;
      }
      description "Price-to-Earnings ratio.";
    }

    leaf dividendYield {
      type decimal64 {
        fraction-digits 2;
      }
      description "Annual dividend yield percentage.";
    }

    leaf eps {
      type decimal64 {
        fraction-digits 2;
      }
      description "Earnings Per Share.";
    }

    leaf week52High {
      type decimal64 {
        fraction-digits 2;
      }
      description "52-week highest trading price.";
    }

    leaf week52Low {
      type decimal64 {
        fraction-digits 2;
      }
      description "52-week lowest trading price.";
    }

    container historicalData {
      description "Dictionary of historical market data, keyed by timestamps.";

      list candleData {
        key "timestamp";
        leaf timestamp {
          type string;
          description "Timestamp marking the beginning of the candle.";
        }

        container oneMinute {
          description "Data for the 1-minute candle.";
          leaf open {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf high {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf low {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf close {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf volume {
            type uint64;
          }
        }

        container fiveMinute {
          description "Optional data for the 5-minute candle.";
          leaf open {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf high {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf low {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf close {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf volume {
            type uint64;
          }
        }
      }
    }
  }
}

Key Properties

The ggStock object includes the following key components:

Property	Description	Example
`symbol`	Stock ticker symbol	`"AAPL"`
`companyName`	Full registered company name	`"Apple Inc."`
`exchange`	Stock exchange where security is listed	`"NASDAQ"`
`industry`	Primary industry classification	`"Technology"`
`currentPrice`	Current stock trading price	`153.80`
`marketCap`	Total market value of outstanding shares	`2436521000000`
`volume`	Number of shares traded in last session	`75844200`
`peRatio`	Price-to-Earnings ratio	`25.98`
`dividendYield`	Annual dividend yield percentage	`0.57`
`eps`	Earnings Per Share	`5.92`
`week52High`	Highest price in past 52 weeks	`179.61`
`week52Low`	Lowest price in past 52 weeks	`124.17`
`historicalData`	Time-series data keyed by timestamps	See detailed example below

Example Data Structure

{
    "symbol": "AAPL",
    "companyName": "Apple Inc.",
    "exchange": "NASDAQ",
    "industry": "Technology",
    "currentPrice": 153.80,
    "marketCap": 2436521000000,
    "volume": 75844200,
    "peRatio": 25.98,
    "dividendYield": 0.57,
    "eps": 5.92,
    "week52High": 179.61,
    "week52Low": 124.17,
    "historicalData": {
        "2023-03-07T09:30:00": {
            "oneMinute": {
                "open": 153.70,
                "high": 153.83,
                "low": 153.65,
                "close": 153.78,
                "volume": 342956
            },
            "fiveMinute": {
                "open": 153.70,
                "high": 154.12,
                "low": 153.65,
                "close": 154.06,
                "volume": 1856324
            }
        },
        "2023-03-07T09:31:00": {
            "oneMinute": {
                "open": 153.79,
                "high": 153.92,
                "low": 153.76,
                "close": 153.85,
                "volume": 287451
            }
        }
        // Additional timestamps with their associated candle data
    }
}

Accessing Data

Stock data can be accessed using the epoch timestamp as an index:

# Access the data for a specific timestamp
timestamp = "2023-03-07T09:30:00"
candle_data = stock_object[timestamp]
 
# Access OHLC data from the 1-minute candle
open_price = candle_data.oneMinute.open
high_price = candle_data.oneMinute.high
low_price = candle_data.oneMinute.low
close_price = candle_data.oneMinute.close
volume = candle_data.oneMinute.volume
 
# Access 5-minute candle data when available
if hasattr(candle_data, "fiveMinute"):
    five_min_close = candle_data.fiveMinute.close

Usage Example

import goldengoose
 
# Get Microsoft stock data
msft = goldengoose.stocks.get("MSFT")
 
# Print company information
print(f"Company: {msft.companyName} ({msft.symbol})")
print(f"Exchange: {msft.exchange}")
print(f"Industry: {msft.industry}")
 
# Print current market data
print(f"Current Price: ${msft.currentPrice}")
print(f"Market Cap: ${msft.marketCap:,}")
print(f"P/E Ratio: {msft.peRatio}")
print(f"EPS: ${msft.eps}")
print(f"Dividend Yield: {msft.dividendYield}%")
 
# Access historical data for the most recent timestamp
current_epoch = goldengoose.get_current_epoch()
candle = msft[current_epoch]
 
# Print OHLC information
print("\nRecent Price Action:")
print(f"Open: ${candle.oneMinute.open}")
print(f"High: ${candle.oneMinute.high}")
print(f"Low: ${candle.oneMinute.low}")
print(f"Close: ${candle.oneMinute.close}")
print(f"Volume: {candle.oneMinute.volume:,}")
 
# Calculate simple metrics
daily_change = candle.oneMinute.close - candle.oneMinute.open
daily_change_pct = (daily_change / candle.oneMinute.open) * 100
print(f"Change: ${daily_change:.2f} ({daily_change_pct:.2f}%)")

Notes

Historical data timestamps are in UTC format
The oneMinute candle data is always present, while fiveMinute data may be optional
Data points are guaranteed to be available for all epochs, even during market gaps
Missing data points are interpolated using the last known value
Access to both 1-minute and 5-minute candles allows for multi-timeframe analysis
The currentPrice field is updated in real-time and may differ slightly from the most recent candle's close price

List