JSON Support

Open

Hi everyone, I setup a few pages on our site to return data in JSON format to help out users developing add-ons and scripts. At the moment these pages are...

Homepage
https://www.steamgifts.com/?format=json

Profiles - Giveaways Created
https://www.steamgifts.com/user/cg?format=json

Profiles - Giveaways Won
https://www.steamgifts.com/user/cg/giveaways/won?format=json

Groups - Giveaways Created
https://www.steamgifts.com/group/SJ7Bu/steamgifts?format=json

Bundle Games
https://www.steamgifts.com/bundle-games?format=json

You can also use existing parameters with these requests. For example, if you wanted to view JSON data for recommended giveaways on our homepage, that have a release date in 2020 or later, you could use...

https://www.steamgifts.com/giveaways/search?format=json&type=recommended&release_date_min=2020-01-01

The previously discussed rate limits also apply to these JSON requests. However, a higher number of results are returned when requesting data in JSON format, so you'll be able to use a fewer number of requests.

All of the responses include page and per_page properties. As expected, these return the current page number and the number of results per page. At the moment 100 results are returned per page, except for the bundle list, which returns 1,000 results per page. These numbers may change in the future, so if you're writing a script don't hardcode the values but instead check if the number of results being returned equals per_page, and if so, request page + 1.

The following information will be returned for giveaways. If the "NULL" column in the below tables is "Yes", that means the property can be null. If the "Always Included" column is "Yes", that means the property will always be returned. For example, name, points, copies, app_id, and package_id will not be returned for open invite only giveaways that you do not have permission to view, and link will never be returned for invite only giveaways you do not have permission to view. The giveaway id is the internal SteamGifts ID for the giveaway. Likewise, the creator or winner id properties correspond to the internal SteamGifts user IDs. These can be useful when dealing with users that change usernames. You'll notice Steam IDs can be null, and that occurs when a user has deleted their account from SteamGifts.

Property	Type	NULL	Always Included
id	int	No	Yes
name	string	Yes	No
points	int	No	No
copies	int	No	No
app_id	int	Yes	No
package_id	int	Yes	No
link	string	No	No
created_timestamp	timestamp	No	Yes
start_timestamp	timestamp	No	Yes
end_timestamp	timestamp	No	Yes
region_restricted	boolean	No	Yes
invite_only	boolean	No	Yes
whitelist	boolean	No	Yes
group	boolean	No	Yes
contributor_level	int	No	Yes
comment_count	int	No	Yes
entry_count	int	No	Yes
creator	object	No	Yes
---- id	int	No	Yes
---- steam_id	string	Yes	Yes
---- username	string	No	Yes

If you're requesting a user's created or won giveaways, the response will include a user object containing properties for the profile. The id is the internal SteamGifts ID for the user.

Property	Type	NULL	Always Included
user	object	No	Yes
---- id	int	No	Yes
---- steam_id	string	Yes	Yes
---- username	string	No	Yes

If you're requesting a group's giveaways, the response will include a group object containing properties for the group. The id is the internal SteamGifts ID for the group and gid is the Steam group ID.

Property	Type	NULL	Always Included
group	object	No	Yes
---- id	int	No	Yes
---- gid	string	No	Yes
---- name	string	No	Yes

When requesting the JSON data for a user's won giveaways the response will include one additional property for each giveaway called received. This value will be true if the user has marked their gift as received and false when it's marked as not received.

Property	Type	NULL	Always Included
received	boolean	No	Yes

There are a couple of additional parameters that can be assigned to requests. It's recommended you do not apply these parameters unless the information is required, since it requires more database queries and the responses are slightly slower. If you set include_feedback=1 in your requests, the response will include a feedback object containing the total number of winners that have marked each giveaway as received, not received, or awaiting feedback.

https://www.steamgifts.com/user/cg?format=json&include_feedback=1

Property	Type	NULL	Always Included
feedback	object	No	Yes
---- received	int	No	Yes
---- not_received	int	No	Yes
---- awaiting_feedback	int	No	Yes

If you set include_winners=1 in your requests, the response will include a winners array containing up to 50 winners for each giveaway. The received property will be true if the winner has marked their gift as received, false when it's marked as not received, and null when the winner has not provided feedback. The id, steam_id, and username may not be included in the response since winners on the site remain anonymous until feedback is provided.

https://www.steamgifts.com/user/cg?format=json&include_winners=1

Property	Type	NULL	Always Included
winners	array	No	Yes
---- id	int	No	No
---- steam_id	string	Yes	No
---- username	string	No	No
---- received	boolean	Yes	Yes

Bundle Games

All of the below fields will be included in the results for bundle games, although any of the values can potentially be null when they don't apply to the game.

https://www.steamgifts.com/bundle-games?format=json

Field	Type	NULL	Always Included
name	string	Yes	Yes
app_id	int	Yes	Yes
package_id	int	Yes	Yes
reduced_value_timestamp	timestamp	Yes	Yes
no_value_timestamp	timestamp	Yes	Yes

3 years ago*

Comment has been collapsed.

37 Comments

godprobe

It's like Christmas! Thank you for all the work that went into adding this!

3 years ago

JSON Support

Bundle Games

🤩