fsdiff
Simple command-line tool to investigate differences between JSON responses in different versions of the Foursquare API.
Installation
npm install fsdiff -g
This should create a globally-available fsdiff
command.
Usage
1. Configuration
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.
2. Running fsdiff
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.
Output
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
.
Specifying endpoints
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.
Examples
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