Skip to content

Commit ecf8678

Browse files
coreyjscoreyjs
authored
- Version 0.4.0 (#4)
* - Version 0.4.0 - Fix: Adds graceful error handling on invalid API keys. - Fix: Adds graceful error handling on 400/404 responses from the API due to their limitations. - Update: Changes “model” module to “prediction” and updates tests to comply. - Update: README.md updated for each available endpoint call, along with info and parameter options. - Feature: Live Prediction Endpoints
1 parent 4925e44 commit ecf8678

10 files changed

Lines changed: 456 additions & 29 deletions

File tree

‎README.md‎

Lines changed: 298 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,17 @@ This is a Python library for interacting with the DataGolf APIs. DataGolf is a g
1414
This is being built to support some ML projects I am working on. I will be
1515
continuing to add more endpoints as I need them. If you have a specific endpoint you need, please open a ticket for submit a PR.
1616

17+
---
18+
## Developer Note:
19+
This is in development. Code structure will change as I get
20+
all the endpoints added. So expect some renaming and convention changes.
1721

22+
### Contact
23+
Im available on [Bluesky](https://bsky.app/profile/coreyjs.dev) for any questions or just general chats about enhancements.
1824

1925
---
20-
# Usage
21-
(Currently this only supports JSON formats, CSV is in progress)
26+
# Usage + Installation & Setup
27+
(Currently this only supports JSON formats, CSV is on the roadmap)
2228

2329
```python
2430
pip install data_golf
@@ -33,16 +39,303 @@ client = DataGolfClient(api_key="YOUR_API_KEY")
3339
client = DataGolfClient(api_key="YOUR_API_KEY", verbose=True)
3440
```
3541

42+
---
43+
44+
# Main Modules
45+
46+
These modules map directly to the [DataGolf API Documentation](https://datagolf.com/api-access) available on their site:
47+
48+
1. General
49+
2. Predictions
50+
3. Live Predictions
51+
52+
The Data Golf API is a paid service via [DataGolf.com](https://datagolf.com/api-access), there they will provide you with an API Key. This library is
53+
only a helper utility, to make interacting and consuming the API easier.
54+
---
3655

3756
# General APIs
3857

58+
### Player List
59+
60+
<details>
61+
<summary>API Endpoint Info</summary>
62+
63+
**Endpoint:** `/get-player-list`
64+
**Method:** GET
65+
**Formats:** JSON
66+
67+
</details>
68+
3969
```python
40-
# Player List
4170
players = client.general.player_list()
71+
```
72+
73+
74+
### Current Season Tour Schedule
75+
76+
<details>
77+
<summary>API Endpoint Info</summary>
78+
79+
**Endpoint:** `/get-schedule`
80+
**Method:** GET
81+
**Formats:** JSON
82+
83+
| Param | Type | Ex |
84+
|-------|--------|---------------------------------------------------------------------------|
85+
| tour | str | all, pga, euro, kft, alt, liv |
4286

43-
# Current Season Tour Schedule
87+
</details>
88+
89+
```python
4490
# Can use optinal parameter 'tour' to filter by tour: pga, euro, kft, alt, liv
4591
tour_schedule = client.general.tour_schedule()
4692
tour_schedule = client.general.tour_schedule(tour="pga")
4793
tour_schedule = client.general.tour_schedule(tour="liv")
48-
```
94+
```
95+
96+
### Field Updates
97+
98+
<details>
99+
<summary>API Endpoint Info</summary>
100+
101+
**Endpoint:** `/field-updates`
102+
**Method:** GET
103+
**Formats:** JSON
104+
105+
| Param | Type | Ex |
106+
|-------|--------|---------------------------------------------------------------------------|
107+
| tour | str | all, pga, euro, kft, alt, liv |
108+
109+
</details>
110+
111+
```python
112+
# tour = pga (default), euro, kft, opp, alt
113+
rsp = client.general.field_updates() # defaults to pga
114+
rsp = client.general.field_updates(tour="kft")
115+
```
116+
117+
---
118+
119+
# Model Prediction APIs
120+
121+
## Rankings
122+
123+
<details>
124+
<summary>API Endpoint Info</summary>
125+
126+
127+
**Endpoint:** `/preds/get-dg-rankings`
128+
**Method:** GET
129+
**Formats:** JSON
130+
131+
</details>
132+
133+
```python
134+
rankings = client.predictions.rankings()
135+
```
136+
137+
## Pre Tournament Predictions
138+
139+
<details>
140+
<summary>API Endpoint Info</summary>
141+
142+
**Endpoint:** `/preds/pre-tournament`
143+
**Method:** GET
144+
**Formats:** JSON
145+
146+
</details>
147+
148+
```python
149+
rsp = client.predictions.pre_tournament()
150+
151+
rsp = client.predictions.pre_tournament(
152+
tour='pga',
153+
dead_heat=True,
154+
odds_format='american'
155+
)
156+
```
157+
158+
## Pre Tournament Prediction Archive
159+
160+
<details>
161+
<summary>API Endpoint Info</summary>
162+
163+
**Endpoint:** `/preds/pre-tournament-archive`
164+
**Method:** GET
165+
**Formats:** JSON
166+
167+
</details>
168+
169+
```python
170+
# Supports optional parameters event_id:, year:, odds_format:
171+
rsp = client.predictions.pre_tournament_pred_archive()
172+
173+
rsp = client.predictions.pre_tournament_pred_archive(
174+
year=2021,
175+
)
176+
```
177+
178+
## Player Skill Decomposition
179+
180+
<details>
181+
<summary>API Endpoint Info</summary>
182+
183+
**Endpoint:** `/preds/player-decompositions`
184+
**Method:** GET
185+
**Formats:** JSON
186+
187+
</details>
188+
189+
```python
190+
# Supports optional parameters tour:
191+
rsp = client.predictions.player_skill_decompositions()
192+
rsp = client.predictions.player_skill_decompositions(tour='alt')
193+
```
194+
195+
## Player Skill Ratings
196+
197+
<details>
198+
<summary>API Endpoint Info</summary>
199+
200+
**Endpoint:** `/preds/skill-ratings`
201+
**Method:** GET
202+
**Formats:** JSON
203+
204+
</details>
205+
206+
```python
207+
# Supports optional param display: (value, rank)
208+
rsp = client.predictions.player_skill_ratings()
209+
rsp = client.predictions.player_skill_ratings(display="rank")
210+
```
211+
212+
## Detailed Approach Skill
213+
214+
<details>
215+
<summary>API Endpoint Info</summary>
216+
217+
**Endpoint:** `/preds/approach-skill`
218+
**Method:** GET
219+
**Formats:** JSON
220+
221+
| Param | Type | Ex |
222+
|--------|--------|---------------------------------------------------------------------------|
223+
| period | str | l24 (last 24 months) (default), <br/> l12 (last 12 months), ytd (year to date) |
224+
225+
</details>
226+
227+
```python
228+
rsp = client.predictions.detailed_approach_skill()
229+
rsp = client.predictions.detailed_approach_skill(period='ytd')
230+
```
231+
232+
## Fantasy Projections
233+
<details>
234+
<summary>API Endpoint Info</summary>
235+
236+
237+
**Endpoint:** `/preds/fantasy-projection-defaults`
238+
**Method:** GET
239+
**Formats:** JSON
240+
241+
| Param | Type | Ex |
242+
|-------|-----|---------------------------------------------------------------|
243+
| tour | str | pga (default), euro, opp (opposite field PGA TOUR event), alt |
244+
| site | str | draftkings (default), fanduel, yahoo |
245+
| slate | str | main (default), showdown, showdown_late, weekend, captain |
246+
247+
</details>
248+
249+
```python
250+
rsp = client.predictions.fantasy_projection()
251+
rsp = client.predictions.fantasy_projection(tour='pga', site='fanduel', slate='showdown')
252+
```
253+
254+
---
255+
256+
# Live Predictions
257+
258+
259+
### Live Model Predictions
260+
261+
<details>
262+
<summary>API Endpoint Info</summary>
263+
264+
265+
**Endpoint:** `/preds/in-play`
266+
**Method:** GET
267+
**Formats:** JSON
268+
269+
| Param | Type | Ex |
270+
|-------------|------|---------------------------------------------------------------|
271+
| tour | str | pga (default), euro, opp (opposite field PGA TOUR event), alt |
272+
| dead_head | bool | False (default), True |
273+
| odds_format | str | percent (default), american, decimal, fraction |
274+
275+
</details>
276+
277+
```python
278+
data = dg.live_predictions.live_in_play()
279+
data = dg.live_predictions.live_in_play(tour='kft', odds_format='american')
280+
```
281+
282+
283+
### Live Tournament Stats
284+
285+
Returns live strokes-gained and traditional stats for every player during PGA Tour tournaments.
286+
287+
288+
<details>
289+
<summary>API Endpoint Info</summary>
290+
291+
292+
**Endpoint:** `/preds/live-tournament-stats`
293+
**Method:** GET
294+
**Formats:** JSON
295+
296+
| Param | Type | Ex |
297+
|---------|---------|---------------------------------------------------------------|
298+
| stats | csv str | Comma-separated list of statistics to be returned. Supports: sg_putt, sg_arg, sg_app, sg_ott, sg_t2g, sg_bs, sg_total, <br/>distance, accuracy, gir, prox_fw, prox_rgh, scrambling |
299+
| round | str | event_avg, 1, 2, 3, 4 |
300+
| display | str | value (default), rank |
301+
302+
</details>
303+
304+
```python
305+
data = dg.live_predictions.live_tournament_stats()
306+
data = dg.live_predictions.live_tournament_stats(stats="sq_arg, sg_bs", disppaly="rank")
307+
```
308+
309+
310+
### Live Hole Scoring Distruibution
311+
312+
Returns live hole scoring averages and distrubutions (birdies, pars, bogeys, etc.) broken down by tee time wave.
313+
314+
315+
<details>
316+
<summary>API Endpoint Info</summary>
317+
318+
319+
**Endpoint:** `/preds/live-hole-stats`
320+
**Method:** GET
321+
**Formats:** JSON
322+
323+
| Param | Type | Ex |
324+
|---------|------|--------------------------------------------------------------|
325+
| tour | str | pga (default), euro, opp (opposite field PGA TOUR event), kft, alt |
326+
| round | str | event_avg, 1, 2, 3, 4 |
327+
| display | str | value (default), rank |
328+
329+
</details>
330+
331+
```python
332+
data = dg.live_predictions.live_hole_stats()
333+
data = dg.live_predictions.live_hole_stats(tour='kft')
334+
```
335+
336+
337+
338+
339+
340+
341+

‎data_golf/api/general.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ def field_updates(self, tour: str = "pga", f_format: str = "json") -> List[dict]
2828
Up-to-the-minute field updates on WDs, Monday Qualifiers, tee times, and fantasy salaries for PGA Tour,
2929
European Tour, and Korn Ferry Tour events. Includes data golf IDs and tour-specific IDs for
3030
each player in the field.
31+
:type tour: str := pga (default), euro, kft, opp, alt
3132
:return:
3233
"""
3334

0 commit comments

Comments
 (0)