forked from koala73/worldmonitor
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathGivingService.openapi.yaml
More file actions
233 lines (233 loc) · 9.89 KB
/
GivingService.openapi.yaml
File metadata and controls
233 lines (233 loc) · 9.89 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
openapi: 3.1.0
info:
title: GivingService API
version: 1.0.0
paths:
/api/giving/v1/get-giving-summary:
get:
tags:
- GivingService
summary: GetGivingSummary
description: GetGivingSummary retrieves a composite global giving activity index and platform breakdowns.
operationId: GetGivingSummary
parameters:
- name: platform_limit
in: query
description: Number of platforms to include (0 = all).
required: false
schema:
type: integer
format: int32
- name: category_limit
in: query
description: Number of category breakdowns to include (0 = all).
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetGivingSummaryResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
properties:
message:
type: string
description: Error message (e.g., 'user not found', 'database connection failed')
description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
FieldViolation:
type: object
properties:
field:
type: string
description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')
description:
type: string
description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
required:
- field
- description
description: FieldViolation describes a single validation error for a specific field.
ValidationError:
type: object
properties:
violations:
type: array
items:
$ref: '#/components/schemas/FieldViolation'
description: List of validation violations
required:
- violations
description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
GetGivingSummaryRequest:
type: object
properties:
platformLimit:
type: integer
format: int32
description: Number of platforms to include (0 = all).
categoryLimit:
type: integer
format: int32
description: Number of category breakdowns to include (0 = all).
description: GetGivingSummaryRequest specifies parameters for retrieving the global giving summary.
GetGivingSummaryResponse:
type: object
properties:
summary:
$ref: '#/components/schemas/GivingSummary'
description: GetGivingSummaryResponse contains the global giving activity summary.
GivingSummary:
type: object
properties:
generatedAt:
type: string
description: Timestamp of the summary generation (ISO 8601).
activityIndex:
type: number
format: double
description: Global giving activity index (0-100 composite score).
trend:
type: string
description: Index trend direction.
estimatedDailyFlowUsd:
type: number
format: double
description: Estimated daily global giving flow in USD (directional, not precise).
platforms:
type: array
items:
$ref: '#/components/schemas/PlatformGiving'
categories:
type: array
items:
$ref: '#/components/schemas/CategoryBreakdown'
crypto:
$ref: '#/components/schemas/CryptoGivingSummary'
institutional:
$ref: '#/components/schemas/InstitutionalGiving'
description: GivingSummary represents a global overview of personal giving activity across platforms.
PlatformGiving:
type: object
properties:
platform:
type: string
minLength: 1
description: Platform name (e.g., "GoFundMe", "GlobalGiving", "JustGiving").
dailyVolumeUsd:
type: number
format: double
description: Estimated daily donation volume in USD.
activeCampaignsSampled:
type: integer
format: int32
description: Number of active campaigns being sampled.
newCampaigns24h:
type: integer
format: int32
description: New campaigns created in the last 24 hours.
donationVelocity:
type: number
format: double
description: Average donation velocity (donations per hour).
dataFreshness:
type: string
description: 'Data freshness: "live", "daily", "weekly", "annual".'
lastUpdated:
type: string
description: Last data update timestamp (ISO 8601).
required:
- platform
description: PlatformGiving represents aggregated giving data from a single crowdfunding platform.
CategoryBreakdown:
type: object
properties:
category:
type: string
description: Category name (e.g., "Medical", "Disaster Relief", "Education").
share:
type: number
format: double
description: Share of total giving activity (0-1).
change24h:
type: number
format: double
description: 24-hour change in share percentage points.
activeCampaigns:
type: integer
format: int32
description: Number of active campaigns in this category.
trending:
type: boolean
description: Trending indicator.
description: CategoryBreakdown represents giving activity within a specific cause category.
CryptoGivingSummary:
type: object
properties:
dailyInflowUsd:
type: number
format: double
description: Total 24h inflow to tracked charity wallets (USD equivalent).
trackedWallets:
type: integer
format: int32
description: Number of tracked charity wallets.
transactions24h:
type: integer
format: int32
description: Number of transactions in the last 24 hours.
topReceivers:
type: array
items:
type: string
description: Top receiving platforms / DAOs.
pctOfTotal:
type: number
format: double
description: Percentage of total giving that is on-chain.
description: CryptoGivingSummary tracks transparent on-chain philanthropy.
InstitutionalGiving:
type: object
properties:
oecdOdaAnnualUsdBn:
type: number
format: double
description: Latest OECD ODA total (annual, USD billions).
oecdDataYear:
type: integer
format: int32
description: Year of latest OECD data.
cafWorldGivingIndex:
type: number
format: double
description: CAF World Giving Index score (latest).
cafDataYear:
type: integer
format: int32
description: Year of latest CAF data.
candidGrantsTracked:
type: integer
format: int32
description: Number of foundation grants tracked (Candid).
dataLag:
type: string
description: Data lag description (e.g., "Quarterly", "Annual").
description: InstitutionalGiving tracks large-scale structured philanthropy and ODA.