Skip to content

Commit 9e227b5

Browse files
author
Shlomi Kushchi
authored
Merge pull request #301 from alpacahq/cleaner_readme_look
Cleaner look for the REST and Streaming methods
2 parents 817a9a6 + b4ed567 commit 9e227b5

File tree

1 file changed

+52
-167
lines changed

1 file changed

+52
-167
lines changed

‎README.md‎

Lines changed: 52 additions & 167 deletions
Original file line numberDiff line numberDiff line change
@@ -99,22 +99,36 @@ Please note that the API is throttled, currently 200 requests per minute, per ac
9999

100100
If the retries are exceeded, or other API error is returned, `alpaca_trade_api.rest.APIError` is raised.
101101
You can access the following information through this object.
102-
103102
- the API error code: `.code` property
104103
- the API error message: `str(error)`
105104
- the original request object: `.request` property
106105
- the original response objecgt: `.response` property
107106
- the HTTP status code: `.status_code` property
108107

109-
### REST.get_account()
110-
Calls `GET /account` and returns an `Account` entity.
111-
112-
### REST.list_orders(status=None, limit=None, after=None, until=None, direction=None, nested=None)
113-
Calls `GET /orders` and returns a list of `Order` entities.
114-
`after` and `until` need to be string format, which you can obtain by `pd.Timestamp().isoformat()`
115-
116-
### REST.submit_order(symbol, qty, side, type, time_in_force, limit_price=None, stop_price=None, client_order_id=None, order_class=None, take_profit=None, stop_loss=None, trail_price=None, trail_percent=None)
117-
Calls `POST /orders` and returns an `Order` entity.
108+
### API REST Methods
109+
110+
| Rest Method | End Point | Result |
111+
| -------------------------------- | -------------------| ------------------------------------------------------------------ |
112+
| get_account() | `GET /account` and | `Account` entity.|
113+
| get_order_by_client_order_id(client_order_id) | `GET /orders` with client_order_id | `Order` entity.|
114+
| list_orders(status=None, limit=None, after=None, until=None, direction=None, nested=None) | `GET /orders` | list of `Order` entities. `after` and `until` need to be string format, which you can obtain by `pd.Timestamp().isoformat()` |
115+
| submit_order(symbol, qty, side, type, time_in_force, limit_price=None, stop_price=None, client_order_id=None, order_class=None, take_profit=None, stop_loss=None, trail_price=None, trail_percent=None)| `POST /orders` | `Order` entity. |
116+
| get_order(order_id) | `GET /orders/{order_id}` | `Order` entity.|
117+
| cancel_order(order_id) | `DELETE /orders/{order_id}` | |
118+
| cancel_all_orders() | `DELETE /orders`| |
119+
| list_positions() | `GET /positions` | list of `Position` entities|
120+
| get_position(symbol) | `GET /positions/{symbol}` | `Position` entity.|
121+
| list_assets(status=None, asset_class=None) | `GET /assets` | list of `Asset` entities|
122+
| get_asset(symbol) | `GET /assets/{symbol}` | `Asset` entity|
123+
| get_barset(symbols, timeframe, limit, start=None, end=None, after=None, until=None) | `GET /bars/{timeframe}` | Barset with `limit` Bar objects for each of the the requested symbols. `timeframe` can be one of `minute`, `1Min`, `5Min`, `15Min`, `day` or `1D`. `minute` is an alias of `1Min`. Similarly, `day` is an alias of `1D`. `start`, `end`, `after`, and `until` need to be string format, which you can obtain with `pd.Timestamp().isoformat()` `after` cannot be used with `start` and `until` cannot be used with `end`.|
124+
| get_aggs(symbol, timespan, multiplier, _from, to)| `GET /aggs/ticker/{symbol}/range/{multiplier}/{timespan}/{from}/{to}` | `Aggs` entity. `multiplier` is the size of the timespan multiplier. `timespan` is the size of the time window, can be one of `minute`, `hour`, `day`, `week`, `month`, `quarter` or `year`. `_from` and `to` must be in `YYYY-MM-DD` format, e.g. `2020-01-15`.|
125+
| get_last_trade(symbol) | `GET /last/stocks/{symbol}` | `Trade` entity|
126+
| get_last_quote(symbol) | `GET /last_quote/stocks/{symbol}` | `Quote` entity|
127+
| get_clock() | `GET /clock` | `Clock` entity|
128+
| get_calendar(start=None, end=None) | `GET /calendar` | `Calendar` entity|
129+
| get_portfolio_history(date_start=None, date_end=None, period=None, timeframe=None, extended_hours=None) | `GET /account/portfolio/history` | PortfolioHistory entity. PortfolioHistory.df can be used to get the results as a dataframe|
130+
131+
### Rest Examples
118132

119133
Below is an example of submitting a bracket order.
120134
```py
@@ -135,61 +149,6 @@ api.submit_order(
135149
)
136150
```
137151

138-
### REST.get_order_by_client_order_id(client_order_id)
139-
Calls `GET /orders` with client_order_id and returns an `Order` entity.
140-
141-
### REST.get_order(order_id)
142-
Calls `GET /orders/{order_id}` and returns an `Order` entity.
143-
144-
### REST.cancel_order(order_id)
145-
Calls `DELETE /orders/{order_id}`.
146-
147-
### REST.cancel_all_orders()
148-
Calls `DELETE /orders`.
149-
150-
### REST.list_positions()
151-
Calls `GET /positions` and returns a list of `Position` entities.
152-
153-
### REST.get_position(symbol)
154-
Calls `GET /positions/{symbol}` and returns a `Position` entity.
155-
156-
### REST.list_assets(status=None, asset_class=None)
157-
Calls `GET /assets` and returns a list of `Asset` entities.
158-
159-
### REST.get_asset(symbol)
160-
Calls `GET /assets/{symbol}` and returns an `Asset` entity.
161-
162-
### REST.get_barset(symbols, timeframe, limit, start=None, end=None, after=None, until=None)
163-
Calls `GET /bars/{timeframe}` for the given symbols, and returns a Barset with `limit` Bar objects
164-
for each of the the requested symbols.
165-
`timeframe` can be one of `minute`, `1Min`, `5Min`, `15Min`, `day` or `1D`. `minute` is an alias
166-
of `1Min`. Similarly, `day` is an alias of `1D`.
167-
`start`, `end`, `after`, and `until` need to be string format, which you can obtain with
168-
`pd.Timestamp().isoformat()`
169-
`after` cannot be used with `start` and `until` cannot be used with `end`.
170-
171-
### REST.get_aggs(symbol, timespan, multiplier, _from, to):
172-
Calls `GET /aggs/ticker/{symbol}/range/{multiplier}/{timespan}/{from}/{to}` and returns the `Aggs` entity.
173-
`multiplier` is the size of the timespan multiplier.
174-
`timespan` is the size of the time window, can be one of `minute`, `hour`, `day`, `week`, `month`, `quarter` or `year`.
175-
`_from` and `to` must be in `YYYY-MM-DD` format, e.g. `2020-01-15`.
176-
177-
### REST.get_last_trade(symbol)
178-
Calls `GET /last/stocks/{symbol}` and returns a `Trade` entity.
179-
180-
### REST.get_last_quote(symbol)
181-
Calls `GET /last_quote/stocks/{symbol}` and returns a `Quote` entity.
182-
183-
### REST.get_clock()
184-
Calls `GET /clock` and returns a `Clock` entity.
185-
186-
### REST.get_calendar(start=None, end=None)
187-
Calls `GET /calendar` and returns a `Calendar` entity.
188-
189-
### REST.get_portfolio_history(date_start=None, date_end=None, period=None, timeframe=None, extended_hours=None)
190-
Calls `GET /account/portfolio/history` and returns a PortfolioHistory entity. PortfolioHistory.df
191-
can be used to get the results as a dataframe.
192-
193152
---
194153

195154
## StreamConn
@@ -265,28 +224,15 @@ conn.run(['trade_updates', 'AM.*'])
265224
You will likely call the `run` method in a thread since it will keep running
266225
unless an exception is raised.
267226

268-
### StreamConn.subscribe(channels)
269-
Request "listen" to the server. `channels` must be a list of string channel names.
270-
271-
### StreamConn.unsubscribe(channels)
272-
Request to stop "listening" to the server. `channels` must be a list of string channel names.
273-
274-
### StreamConn.run(channels)
275-
Goes into an infinite loop and awaits for messages from the server. You should
276-
set up event listeners using the `on` or `register` method before calling `run`.
277-
278-
### StreamConn.on(channel_pat)
279-
As in the above example, this is a decorator method to add an event handler function.
280-
`channel_pat` is used as a regular expression pattern to filter stream names.
281-
282-
### StreamConn.register(channel_pat, func)
283-
Registers a function as an event handler that is triggered by the stream events
284-
that match with `channel_path` regular expression. Calling this method with the
285-
same `channel_pat` will overwrite the old handler.
227+
| StreamConn Method | Description |
228+
| -------------------------------- | -------------------------------------------------------------------------------------- |
229+
| subscribe(channels) | Request "listen" to the server. `channels` must be a list of string channel names.|
230+
| unsubscribe(channels) | Request to stop "listening" to the server. `channels` must be a list of string channel names.|
231+
| run(channels) | Goes into an infinite loop and awaits for messages from the server. You should set up event listeners using the `on` or `register` method before calling `run`. |
232+
| on(channel_pat) | As in the above example, this is a decorator method to add an event handler function. `channel_pat` is used as a regular expression pattern to filter stream names.|
233+
| register(channel_pat, func) | Registers a function as an event handler that is triggered by the stream events that match with `channel_path` regular expression. Calling this method with the same `channel_pat` will overwrite the old handler.|
234+
| deregister(channel_pat) | Deregisters the event handler function that was previously registered via `on` or `register` method. |
286235

287-
### StreamConn.deregister(channel_pat)
288-
Deregisters the event handler function that was previously registered via `on` or
289-
`register` method.
290236

291237
#### Debugging
292238
Websocket exceptions may occur during execution.
@@ -347,87 +293,26 @@ df = api.polygon.historic_agg_v2('AAPL', 1, 'minute', _from=start, to=end).df
347293
## polygon/REST
348294
It is initialized through the alpaca `REST` object.
349295

350-
### polygon/REST.exchanges()
351-
Returns a list of `Exchange` entity.
352-
353-
### polygon/REST.symbol_type_map()
354-
Returns a `SymbolTypeMap` object.
355-
356-
### polygon/REST.historic_trades_v2(symbol, date,timestamp=None, timestamp_limit=None, reverse=None, limit=None)
357-
Returns a `TradesV2` which is a list of `Trade` entities.
358-
359-
- `date` is a date string such as '2018-2-2'. The returned quotes are from this day only.
360-
- `timestamp` is an integer in Unix Epoch nanoseconds as the lower bound filter, exclusive.
361-
- `timestamp_limit` is an integer in Unix Epoch nanoseconds as the maximum timestamp allowed in the results.
362-
- `limit` is an integer for the number of ticks to return. Default and max is 50000.
363-
364-
### polygon/TradesV2.df
365-
Returns a pandas DataFrame object with the ticks returned by `historic_trades_v2`.
366-
367-
### polygon/REST.historic_quotes_v2(symbol, date,timestamp=None, timestamp_limit=None, reverse=None, limit=None)
368-
Returns a `QuotesV2` which is a list of `Quote` entities.
369-
370-
- `date` is a date string such as '2018-2-2'. The returned quotes are from this day only.
371-
- `timestamp` is an integer in Unix Epoch nanoseconds as the lower bound filter, exclusive.
372-
- `timestamp_limit` is an integer in Unix Epoch nanoseconds as the maximum timestamp allowed in the results.
373-
- `limit` is an integer for the number of ticks to return. Default and max is 50000.
374-
375-
### polygon/QuotesV2.df
376-
Returns a pandas DataFrame object with the ticks returned by the `historic_quotes_v2`.
377-
378-
### polygon/REST.historic_agg_v2(self, symbol, multiplier, timespan, _from, to, unadjusted=False, limit=None)
379-
Returns an `AggsV2` which is a list of `Agg` entities. `AggsV2.df` gives you the DataFrame
380-
object.
381-
382-
- `multiplier` is an integer affecting the amount of data contained in each Agg object.
383-
- `timespan` is a string affecting the length of time represented by each Agg object. It is one of the following values:
384-
- `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`
385-
- `_from` is an Eastern Time timestamp string/object that filters the result for the lower bound, inclusive. we accept the date in these formats:
386-
datetime.datetime, datetime.date, pd.Timestamp, datetime.timestamp,
387-
isoformat string (YYYY-MM-DD)
388-
- `to` is an Eastern Time timestamp string that filters the result for the upper bound, inclusive. we support the same formats as the _from field
389-
- `unadjusted` can be set to true if results should not be adjusted for splits.
390-
- `limit` is an integer to limit the number of results. 3000 is the default and max value.
391-
392-
The returned entities have fields relabeled with the longer name instead of shorter ones.
393-
For example, the `o` field is renamed to `open`.
394-
395-
### polygon/Aggs.df
396-
Returns a pandas DataFrame object with the ticks returned by `hitoric_agg_v2`.
397-
398-
### polygon/REST.daily_open_close(symbol, date)
399-
Returns a `DailyOpenClose` entity.
400-
401-
### poylgon/REST.last_trade(symbol)
402-
Returns a `Trade` entity representing the last trade for the symbol.
403-
404-
### polygon/REST.last_quote(symbol)
405-
Returns a `Quote` entity representing the last quote for the symbol.
406-
407-
### polygon/REST.condition_map(ticktype='trades')
408-
Returns a `ConditionMap` entity.
409-
410-
### polygon/REST.company(symbol)
411-
Returns a `Company` entity if `symbol` is string, or a
412-
dict[symbol -> `Company`] if `symbol` is a list of string.
413-
414-
### polygon/REST.dividends(symbol)
415-
Returns a `Dividends` entity if `symbol` is string, or a
416-
dict[symbol -> `Dividends`] if `symbol is a list of string.
417-
418-
### polygon/REST.splits(symbol)
419-
Returns a `Splits` entity for the symbol.
420-
421-
### polygon/REST.earnings(symbol)
422-
Returns an `Earnings` entity if `symbol` is string, or a
423-
dict[symbol -> `Earnings`] if `symbol` is a list of string.
424-
425-
### polygon/REST.financials(symbol)
426-
Returns an `Financials` entity if `symbol` is string, or a
427-
dict[symbol -> `Financials`] if `symbol` is a list of string.
428-
429-
### polygon/REST.news(symbol)
430-
Returns a `NewsList` entity for the symbol.
296+
| REST Method | Description |
297+
| -------------------------------- | -------------------------------------------------------------------------------------- |
298+
| exchanges() | Returns a list of `Exchange` entity.|
299+
| symbol_type_map() | Returns a `SymbolTypeMap` object.|
300+
| historic_trades_v2(symbol, date, timestamp=None, timestamp_limit=None, reverse=None, limit=None) | Returns a `TradesV2` which is a list of `Trade` entities. `date` is a date string such as '2018-2-2'. The returned quotes are from this day only. `timestamp` is an integer in Unix Epoch nanoseconds as the lower bound filter, exclusive. `timestamp_limit` is an integer in Unix Epoch nanoseconds as the maximum timestamp allowed in the results. `limit` is an integer for the number of ticks to return. Default and max is 50000. |
301+
| TradesV2.df | Returns a pandas DataFrame object with the ticks returned by `historic_trades_v2`. |
302+
| historic_quotes_v2(symbol, date, timestamp=None, timestamp_limit=None, reverse=None, limit=None)| Returns a `QuotesV2` which is a list of `Quote` entities. `date` is a date string such as '2018-2-2'. The returned quotes are from this day only. `timestamp` is an integer in Unix Epoch nanoseconds as the lower bound filter, exclusive. `timestamp_limit` is an integer in Unix Epoch nanoseconds as the maximum timestamp allowed in the results. `limit` is an integer for the number of ticks to return. Default and max is 50000. |
303+
| QuotesV2.df | Returns a pandas DataFrame object with the ticks returned by the `historic_quotes_v2`.|
304+
| historic_agg_v2(self, symbol, multiplier, timespan, _from, to, unadjusted=False, limit=None)| Returns an `AggsV2` which is a list of `Agg` entities. `AggsV2.df` gives you the DataFrame object.<br> - `multiplier` is an integer affecting the amount of data contained in each Agg object. <br> -`timespan` is a string affecting the length of time represented by each Agg object. It is one of the following values: `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`. <br> - `_from` is an Eastern Time timestamp string/object that filters the result for the lower bound, inclusive. we accept the date in these formats: datetime.datetime, datetime.date, pd.Timestamp, datetime.timestamp, isoformat string (YYYY-MM-DD).<br> - `to` is an Eastern Time timestamp string that filters the result for the upper bound, inclusive. we support the same formats as the _from field.<br> - `unadjusted` can be set to true if results should not be adjusted for splits.<br> - `limit` is an integer to limit the number of results. 3000 is the default and max value. <br>The returned entities have fields relabeled with the longer name instead of shorter ones. For example, the `o` field is renamed to `open`.|
305+
| Aggs.df | Returns a pandas DataFrame object with the ticks returned by `hitoric_agg_v2`.|
306+
| daily_open_close(symbol, date) | Returns a `DailyOpenClose` entity.|
307+
| last_trade(symbol) | Returns a `Trade` entity representing the last trade for the symbol.|
308+
| last_quote(symbol) | Returns a `Quote` entity representing the last quote for the symbol.|
309+
| condition_map(ticktype='trades') | Returns a `ConditionMap` entity.|
310+
| company(symbol) | Returns a `Company` entity if `symbol` is string, or a dict[symbol -> `Company`] if `symbol` is a list of string.|
311+
| dividends(symbol) | Returns a `Dividends` entity if `symbol` is string, or a dict[symbol -> `Dividends`] if `symbol` is a list of string.|
312+
| splits(symbol) | Returns a `Splits` entity for the symbol.|
313+
| earnings(symbol) | Returns an `Earnings` entity if `symbol` is string, or a dict[symbol -> `Earnings`] if `symbol` is a list of string.|
314+
| financials(symbol) | Returns an `Financials` entity if `symbol` is string, or a dict[symbol -> `Financials`] if `symbol` is a list of string. |
315+
| news(symbol) | Returns a `NewsList` entity for the symbol.|
431316

432317
## Support and Contribution
433318

0 commit comments

Comments
 (0)