Browse
Category
DiscussionsAnnouncements

JSON Support

Open
cg
(Administrator)

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
Dyna18

Is it possible to also add the following information to the group response?

  • List of users who entered a giveaway
  • List of groups a giveaway is filtered on
3 years ago
Permalink

Comment has been collapsed.

Sign in through Steam to add a comment.