Simple command-line tool to investigate differences between JSON responses in different versions of the Foursquare API.
npm install fsdiff -g
This should create a globally-available fsdiff
command.
You need to configure fsdiff before running it. To do this, you're going to need a Foursquare API client ID, client secret, and optionally an OAuth token. You can use any existing client ID or secrets you may already have (see https://foursquare.com/developers/apps), or you can create a new ID/secret pair. If you don't have your OAuth token readily available, Runscope's OAuth token generator is a nifty tool to help with that.
To configure fsdiff, run:
fsdiff config
You'll be prompted to enter in your credentials (copy + pasting them is fine). A config file will be saved in your home directory.
fsdiff --v1=YYYYMMDD --v2=YYYYMMDD [ENDPOINT [ENDPOINT ...]] [-o OUTPUT_DIR]
v1
and v2
are the only required parameters, and are the two versions of the Foursquare API
you want to compare responses for. By default, fsdiff outputs to stdout a diff of the two responses
from Foursquare in unified diff format. Unless specific
endpoints are specified (see below), fsdiff will run over all Foursquare API endpoints.
If you specify the -o
flag with a directory name, instead of printing, fsdiff will output to subfolders
in the specified directory. Each subfolder will correspond to a Foursquare API endpoint
and will include three files, two of the raw API responses in JSON, and one diff file of the two:
v1.json
, v2.json
, endpoint.diff
.
Instead of running over all API endpoints, you can specify specific ones as parameters to fsdiff. The following are valid parameter values (these can also be found in lib/tests.json):
checkins-CHECKIN_ID
checkins-CHECKIN_ID-likes
checkins-recent
events-EVENT_ID
events-categories
events-search
lists-LIST_ID
lists-LIST_ID-ITEM_ID
lists-LIST_ID-saves
multi
pages-PAGE_ID-venues
pages-USER_ID
pages-USER_ID-similar
pages-search
photos-PHOTO_ID
settings-SETTING_ID
settings-all
specials-SPECIAL_ID
specials-search
tips-TIP_ID
tips-TIP_ID-likes
tips-TIP_ID-listed
tips-TIP_ID-saves
tips-search
updates-notifications
users-USER_ID
users-USER_ID-badges
users-USER_ID-checkins
users-USER_ID-friends
users-USER_ID-lists
users-USER_ID-mayorships
users-USER_ID-photos
users-USER_ID-tips
users-USER_ID-todos
users-USER_ID-venuehistory
users-USER_ID-venuestats
users-leaderboard
users-requests
users-search
users-suggest
venues-VENUE_ID
venues-VENUE_ID-events
venues-VENUE_ID-herenow
venues-VENUE_ID-hours
venues-VENUE_ID-likes
venues-VENUE_ID-links
venues-VENUE_ID-listed
venues-VENUE_ID-menu
venues-VENUE_ID-nextvenues
venues-VENUE_ID-photos
venues-VENUE_ID-similar
venues-VENUE_ID-tips
venues-categories
venues-explore
venues-search
venues-suggestcompletion
venues-trending
Notably missing from the endpoints that fsdiff supports are any endpoints that require merchant authentication.
Basic usage: seeing what's changed in the explore endpoint since last year
$ fsdiff --v1=20130101 --v2=20140301 venues-explore
Index: venues-explore.diff
===================================================================
--- venues-explore.diff v=20130101
+++ venues-explore.diff v=20140301
@@ -6,10 +6,10 @@
"suggestedFilters": {
"header": "Tap to show:",
"filters": [
{
+ "name": "Open now",
+ "key": "openNow"
- "name": "With specials",
- "key": "specials"
},
{
"name": "$-$$$$",
"key": "price"
@@ -37,16 +37,10 @@
"name": "recommended",
"items": [
{
"reasons": {
+ "count": 0,
+ "items": []
- "count": 2,
- "items": [
- {
- "summary": "Lots of people like this place",
- "type": "general",
- "reasonName": "rawLikesReason"
- }
- ]
},
"venue": {
"id": "45c5a7c9f964a52050421fe3",
"name": "Powerhouse Arena",
Output the diff between a Foursquare API version last year and this year across all endpoints to
a directory called out
:
$ fsdiff --v1=20130101 --v2=20140301 -o out
...
All done!
$ cd out/venues-VENUE_ID
$ ls
20130101.json 20140301.json venues-VENUE_ID.diff