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.

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

3 years ago
Permalink

Comment has been collapsed.

Very cool, cg!

3 years ago
Permalink

Comment has been collapsed.

Thank you for providing us with better tools to work with, they are really helpful!

Now it's our turn to adapt our tools/scripts/bots to use them and reduce the stress that we generate to the server by scrapping the site.

3 years ago
Permalink

Comment has been collapsed.

wow, this is great awesome

3 years ago
Permalink

Comment has been collapsed.

Deleted

This comment was deleted 1 year ago.

3 years ago
Permalink

Comment has been collapsed.

Deleted

This comment was deleted 2 years ago.

3 years ago
Permalink

Comment has been collapsed.

soooo helping the bots?

3 years ago
Permalink

Comment has been collapsed.

Thank you so much cg for all your hard work!

3 years ago
Permalink

Comment has been collapsed.

Oh thank you, I love JSON. He was great in Transporter and The Expendables!

3 years ago
Permalink

Comment has been collapsed.

This pun required a certain STATHAM of mind I cannot follow.

Or maybe I can?!

3 years ago
Permalink

Comment has been collapsed.

I'll never support JSON.

3 years ago
Permalink

Comment has been collapsed.

PRESS "X" TO JSOoooooooN!

View attached image.
3 years ago
Permalink

Comment has been collapsed.

This is huge! Thank you, cg!

3 years ago
Permalink

Comment has been collapsed.

Cool.

3 years ago
Permalink

Comment has been collapsed.

Thank you for implementing JSON support, this it very anticipated feature!
However, I have some suggestions to make it more useful for developers.

  1. Implement request to get all information about one particular giveaway, something like
    https://www.steamgifts.com/giveaway/bPB69/?format=json
    Result should include creator, winners, entries, groups, comments, actual game, cost in points. Would be great if it will also include additional information, such as: is game bundled/no value and/or steamID64's of groups (if any) and users (creator, winners, entries). Of course information returned should respect access rights, so if somebody can't get into GA - they won't get entries/groups (but will get the rest). This alone will allow to reduce requests greatly - instead of 5+ requests (main page, bundled page, groups page, winners page, entries page, resolve of group and user to steamID) it will be just one.

  2. If for some reason you can't include additional information about game in request above, would be nice to have some special request to get game info: cost in points, bundled/no values status. Something like
    https://www.steamgifts.com/appinfo/606880/?format=json

  3. In all requests pagination should be user-defined, and optional. so, request
    https://www.steamgifts.com/user/cg?format=json
    should return ALL giveaways user created, and
    https://www.steamgifts.com/user/cg?format=json&per_page=100
    should return first page with 100 results.
    Allow developers to get what they need without having to request it in parts, it will be both easier for them and less load on servers.

  4. In addition to 3, it would be nice to have limits by certain dates, not by pages. For example,
    https://www.steamgifts.com/user/cg?format=json&from_date=2020-01-01
    should result in giveaways for this year, but not before. and
    https://www.steamgifts.com/user/cg?format=json&from_date=2020-01-01&to_date=2020-01-31
    should result in giveaways for January.
    While to_date is optional, from_date is actually crucial. With this, tool developers can once request ALL giveaways, cache it, and then request only giveaways added since last check. Maybe this should be from_datetime, not just date, it will be even better. It may be even in unix time format, no need for it to be human readable, that's api after all.

  5. In addition to 3 and 4, would be great to have another filter to get only active giveaways. It does not make any sense for main page of SG or won games by user, but it makes a lot of sense for user created game or group pages. For example
    https://www.steamgifts.com/group/SJ7Bu/steamgifts?format=json&active=1
    should return only active (not ended yet) giveaways. It many cases only this data is important, so there is no reason to return all data instead.

3 years ago
Permalink

Comment has been collapsed.

+1 to the "date" options

3 years ago
Permalink

Comment has been collapsed.

In addition to 3 and 4, would be great to have another filter to get only active giveaways.

Couldn't you just use the end_timestamp property for this? You'd have to do an extra step of getting the current datetime value, but it's doable, yeah?

3 years ago
Permalink

Comment has been collapsed.

Yes, you are right, IF there will be filter by end_timestamp it will be possible to use it to get only active giveaways too.

3 years ago
Permalink

Comment has been collapsed.

SGTools is now updated and fully using the JSON responses, thanks a lot :)

3 years ago
Permalink

Comment has been collapsed.

And thank you :)

3 years ago
Permalink

Comment has been collapsed.

And thank you for your continued hard work!

3 years ago
Permalink

Comment has been collapsed.

Good news and thanks for the update!

3 years ago
Permalink

Comment has been collapsed.

Thanks for the update and your work. I appreciate it a lot :o)

3 years ago
Permalink

Comment has been collapsed.

Deleted

This comment was deleted 3 years ago.

3 years ago
Permalink

Comment has been collapsed.

Thank you.

🤩

3 years ago
Permalink

Comment has been collapsed.

👍🏻

3 years ago
Permalink

Comment has been collapsed.

Amazing, thanks a lot for this!

3 years ago
Permalink

Comment has been collapsed.

Deleted

This comment was deleted 1 year ago.

3 years ago
Permalink

Comment has been collapsed.

Good job thank you! :)

3 years ago
Permalink

Comment has been collapsed.

You are doing your best to improve the site. I am very grateful for your hard work.

3 years ago
Permalink

Comment has been collapsed.

Nice addition!

3 years ago
Permalink

Comment has been collapsed.

awesome

3 years ago
Permalink

Comment has been collapsed.

It's currently impossible to get to group info without knowing the full URL, which makes the whole API endpoint pointless. Please consider making https://www.steamgifts.com/group/SJ7Bu?format=json or https://www.steamgifts.com/group/SJ7Bu/?format=json possible to call.

Consider adding sg_name to giveaways response, it's stupid to extract it from the url. Also, I'd appreciate having internal ID of the Steam asset there, which is being used in request for hiding games on SG.

3 years ago*
Permalink

Comment has been collapsed.

That's a good idea.

Isn't the group name part the same one used in steam's group link? and since steam servers aren't rate limited, you can follow "http://www.steamcommunity.com/gid/103582791432125620" and get the group name from that, avoiding the additional request to SG.

3 years ago
Permalink

Comment has been collapsed.

Thank you for creating this. This was a long desired wish that I have for 6 years now.

3 years ago
Permalink

Comment has been collapsed.

sweet!

3 years ago
Permalink

Comment has been collapsed.

Sign in through Steam to add a comment.