SWHelp:StampWants API Request
From StampWantsWiki
All requests of any kind are made by accessing the StampWants API File Command URL with your username, password and type set. The result sent back to you will be a csv file containing the information you requested.
Contents |
Creating a Basic Request
To request information from StampWants you need to set the type variable in the File Command URL:
http://www.stampwants.com/filecommand.php?username=myUserName&password=myPassWord&type=XXXXX
Where XXXXX can be:
| Field Name | Description |
|---|---|
| selling | To request complete information (including number of bids and high bidder) regarding your active (open) listings. |
| sold | To request complete information (including detailed information on the winner) regarding your sold items. |
| unsold | To request complete information regarding your unsold (items which closed without a winner) items. |
| bidding | To request information regarding the items you are currently bidding on (open listings). |
| watching | To request information regarding the items you are watching (open and closed [unless otherwise specified] listings). |
| won | To request complete information (including detailed information on the seller) regarding the items you have won or purchased. |
| lost | To request information regarding the items you did not win (closed listings). |
| pending | To request information regarding Public Auction and Mail Sale items, which you bid on and are now closed, and whose prices realized have not yet been published. |
Creating a Proper Request
Accessing the StampWants API File Command URL with your username and password set, and the type set to one of the above values is the minimum requirement to access the StampWants API. However, we recommend that you do not access the StampWants API with only your username, password and type set. The reason is that with only these variables set the StampWants API will return ALL applicable results. So, if you have 20,000 active listings and call:
http://www.stampwants.com/filecommand.php?username=myUserName&password=myPassWord&type=selling
The resulting response will be a csv file containing full details on all 20,000 of your listings. The resulting csv file can be several hundred Megabytes (100MB+) in size. Requesting such a file will not only slow your program down, but our server as well. We ask that you limit making any request that will result such a large file to no more than once a day (preferably once a week!)
To properly use the StampWants API, and request only the information you need you will need to set additional variables in the StampWants API File Command. Depending on which type of information you are requesting, different variables are available.
Variables Available to set in the File Command URL
PLEASE NOTE: All variable names and values are case sensitive.
| Variable | Allowed Values | Can Be Used With | Description |
|---|---|---|---|
| FCid | Integer Number (StampWants ID Number) | all | Setting this variable will limit the results returned to the single listing which matches this StampWants ID Number. This variable can not be used if either the FCprivateid or keywords variable is set. Note: When used with the 'type=sold' more than one result may be returned if the item originally had a quantity greater than 1. |
| FCprivateid | Text (Private ID) | all | Setting this variable will limit the results returned to listings matching this private id. This variable can not be used if either the FCid or keywords variable is set. |
| keywords | Text | all | Setting this variable will limit the results returned to listings matching the keywords you enter in the title of the item. This variable can not be used if either the FCid or FCprivateid variable is set. Note: This field is NOT case sensitive. |
| FCdateFrom | Date (YYYY-MM-DD HH:MM:SS) [24 Hour Format EST/EDT] or lastdownload | all (*selling - only when FCdateType is set) | Setting this variable will limit the results returned to listings which were either sold, end or ended after and including this date. If the value is set to 'lastdownload' the FCdateFrom will be the last time you accessed the StampWants API File Command for this specific type, and used the 'lastdownload' value. Note: When using the lastdownload option the FCdateTo will be ignored. * Important - Please read the Important Notes on Date & Time section below. |
| FCdateTo | Date (YYYY-MM-DD HH:MM:SS) [24 Hour Format EST/EDT] | sold | Setting this variable will limit the results returned to listings which were either sold, end or ended before and including this date. * Important - Please read the Important Notes on Date & Time section below. |
| FCdateType | startdate (selling only) paiddate or shippeddate (sold only) | sold | For 'type=selling' by default you cannot use the FCdateFrom and FCdateTo variables. However, if you set the FCdateType to startdate you can filter by date for the date the listings were started. For 'type=sold' the default is to search by the end date when using FCdateFrom and FCdateTo, however, you can instead filter by either the paid date or the shipped date. Note: Items will only have paid or shipped dates if they have been marked paid or shipped, or if the were marked paid or shipped, and later marked unpaid and not shipped). |
| limit | Integer Number | all | Setting this variable will limit the results returned to at most this many results. |
| showType | auction, fixed, store or public | all | Setting this variable will limit the results returned to only items which match the listing type specified. auction for Auction Items, fixed for Fixed Price Listings, store for Store Listings and public for Public Auction and Mail Sale listings. You may use more than one of the values by separating them with a comma (e.g. fixed,store). |
| category | Integer Number (must be a valid Category Code, as found on the Category Code page) | all | Setting this variable will limit the results returned to listings which are/were listed in this category. |
| activeBids | 0 or 1 | selling | Setting this variable will limit the results returned to listings with active bids only. |
| bidder | Text (StampWants Username or Partial Username) | selling, sold or unsold | Setting this variable will limit the results returned to listings which were bid on or won by this bidder. Note: This variable will also match partial usernames starting from the beginning (e.g. frank will match both frank, frankenstein, and frank15), as a result you may want to have your program or application check to make sure the bidder is the exact bidder you were looking for. |
| bidderEmail | Text | sold | Setting this variable will limit the results returned to listings which were bid on or won by the bidder with this email address. Note: This variable will also match partial email addresses starting from the beginning (e.g. frank will match both frank@stampwants.com, frank@gmail.com, and frank15@stampwants.com), as a result you may want to have your program or application check to make sure the bidder is the exact bidder you were looking for. |
| FCunPaid | 0 or 1 | sold or won | Setting this variable will limit the results returned to listings which were not yet paid for. |
| FCunShipped | 0 or 1 | sold | Setting this variable will limit the results returned to listings which were not yet shipped. |
| FCunReceived | 0 or 1 | won | Setting this variable will limit the results returned to listings which were not yet received. |
| FCunRelisted | 0 or 1 | unsold | Setting this variable will limit the results returned to listings which were not relisted. |
Important Notes on Date & Time
When requesting information using the FCdateFrom and FCdateTo variables, it is important to understand that all date and times you request will be based off of our official time, and in EST/EDT only. You can find our official time on our home page, at the top left. The time that your program or application is using may, and probably will be, off from our official time (usually by a few seconds, but depending on your program or application it could be minutes of more). This may cause problems when requesting data if not properly accounted for.
If your program or application's time is slower than the StampWants Official time in general there should be no major issues. However, you should still be aware of the delay in data this may cause. For example, if you sell an item on StampWants at 2008-05-30 16:05:00 (StampWants Official time) and you are requesting the sold items data every minute, by manually setting the date and time to your program or application's current time, and one minute in the past, you will not receive the information on the item you sold at 2008-05-30 16:05:00 until your program or application believes it to be that time. So, if your program or application believes it to be 2008-05-30 16:00:00, you might not request the information on your newly sold item until 5 minutes after it has sold.
One way to easily avoid this issue of data being delayed is to use the 'lastdownload' option for the FCdateFrom. This will ensure that the request you make is based off of StampWants Official time only.
If your program or application's time is faster than the StampWants Official time you need to carefully take this into account, or you could miss downloading data you want. The easiest way to explain why you may miss downloading data is by looking at an example:
In this example StampWants Official time will be 2008-05-30 18:00:00 and the time in your program or application will be 2008-05-30 18:02:00 (2 minutes faster than StampWants Official time). Now, let's imagine you want to request information for all sold items within the last minute. You set FCdateFrom=2008-05-30 18:01:01 and FCdateTo=2008-05-30 18:02:00. Now you send your request to the StampWants API. The StampWants API then replies that there is no data for your request. This is because on StampWants, the time is only 2008-05-30 18:00:00, so nothing could have sold between two dates in the future yet. If you then wait one minute, and increase both the FCdateFrom and FCdateTo by one minute, you will again request information for items sold at a time which did not occur yet. So, as you can see, you would never receive any information.
While the above case may seem a bit extreme, even if your program or application is only ahead of StampWants Official time by 5 seconds, if you are manually setting the date range based on your program or application's time, you may be missing 5 seconds of data, every time you make a request. So even if you make a request every hour, you won't ever want to loose 5 or even 1 seconds worth of data.
Again, one way to easily avoid this issue of data being lost is to use the 'lastdownload' option for the FCdateFrom. This will ensure that the request you make is based off of StampWants Official time only.
Alternatively, another way to ensure you never miss any data is to overlap your requests. For example you can make sure that if you want to request the sold data every minute, instead of calling the StampWants API with the FCdateFrom set to one minute in the past, set it 30 minutes in the past. Essentially each minute you would request all data from 30 minutes ago according to your server, to NOW according to your server. This way you overlap the data by 30 minutes. So, as long as your program or application's time is not more than 30 minutes ahead of our time, you will never miss any data. However, you will receive duplicate information. You should be able to easily determine new information from information you already received by either the StampWants ID or the Transaction ID. The StampWants ID will be enough to check, unless your item has a multiple quantity and you are checking sold data, in which case you will want to check the Transaction ID, which is unique to each sale (per item/buyer).
Examples of Proper Requests
To request complete information on an active listing, that you own, with a StampWants Id of 123456:
http://www.stampwants.com/filecommand.php?username=myUserName&password=myPassWord&type=selling&FCid=123456
To request complete information on an all active listings with bids:
http://www.stampwants.com/filecommand.php?username=myUserName&password=myPassWord&type=selling&activeBids=1
To request complete information on items you have sold since the last time you requested information on items you have sold, and used the 'lastdownload' value for the 'FCdateFrom' variable:
http://www.stampwants.com/filecommand.php?username=myUserName&password=myPassWord&type=sold&FCdateFrom=lastdownload
To request complete information on items you have sold since and including 2008-05-01 10:00:00 to 2008-05-01 10:59:59
http://www.stampwants.com/filecommand.php?username=myUserName&password=myPassWord&type=sold&FCdateFrom=2008-05-01 10:00:00&FCdateTo=2008-05-01 10:59:59
To request complete information on items you have sold to a buyer with the username of theirUserName
http://www.stampwants.com/filecommand.php?username=myUserName&password=myPassWord&type=sold&bidder=theirUserName
CSV File Returned By Type
The csv file returned to you will have different columns and data depending on the type of request you make. Below we will list the data you should expect to see based on the request you make. The first line of the csv file will contain the names of each column - the column headings. Please note that if no data is returned you should still receive the column headings back. If you do not receive a csv file with at least 1 row consisting of the column headings your File Command URL may be set incorrectly. Please first check for any issues in your program or application and the File Command URL you are sending. If you cannot correct the issue, please contact us for assistance.
You can find full details on the fields returned by the StampWants API, broken down by type, here: StampWants API CSV Return Specifications
