I’ve used Survey Monkey’s API for
a while, and though it’s pretty powerful, there’s
a lot of boilerplate each time it’s used
in a new project, and the json it returns needs
a bunch of processing to be able to use the raw information. So I’ve finally got around to releasing
a .NET library you can use to consume the API more easily.
The main advantages are:
Only ever deal with strongly-typed .NET objects, making everything much more robust and
a lot faster to get going
Automatically handles things like rate-limiting and paging through results
Uses combinations of endpoints to get all relevant data for you, and processes raw response data to map responses to questions
To start, either install it using NuGet with PM> Install-Package SurveyMonkeyApi (easier option), or grab the source from https://github.com/bcemmett/SurveyMonkeyApi if you prefer to build it yourself. You’ll also need to have signed up for
a developer account with Survey Monkey, and have both your API key and an OAuth token.
A simple usage would be something like:
string apiKey = "KEY";
string token = "TOKEN";
var sm =
new SurveyMonkeyApi(apiKey, token);
List<Survey> surveys = sm.GetSurveyList();
The surveys object is now
a list of surveys with all the information available from the /surveys/get_survey_list API endpoint, including the title, id, date it was created and last modified, language, number of questions / responses, and relevant urls. If there are more than 1000 surveys
in your account, the library pages through the results for you, making multiple requests to get
a complete list of surveys.
All the filtering available
in the API can be controlled using .NET objects. For example you might only want surveys created
in the last year and containing “pineapple”
in the title:
var settings =
new GetSurveyListSettings
{
Title = "pineapple",
StartDate = DateTime.Now.AddYears(-1)
};
List<Survey> surveys = sm.GetSurveyList(settings);
By default, whenever optional fields can be requested with
a response, they will all be fetched for you. You can change this behaviour if for
some reason you explicitly don’t want the information, using
var settings =
new GetSurveyListSettings
{
OptionalData =
new GetSurveyListSettingsOptionalData
{
DateCreated = false,
AnalysisUrl = false
}
};
Survey Monkey’s 7 read-only endpoints are supported, and the other 4 which make modifications to data might be supported
in the future. The endpoints are:
Endpoint
Method
Object returned
/surveys/get_survey_list
GetSurveyList()
List<Survey>
/surveys/get_survey_details
GetSurveyDetails()
Survey
/surveys/get_collector_list
GetCollectorList()
List<Collector>
/surveys/get_respondent_list
GetRespondentList()
List<Respondent>
/surveys/get_responses
GetResponses()
List<Response>
/surveys/get_response_counts
GetResponseCounts()
Collector
/user/get_user_details
GetUserDetails()
UserDetails
/batch/create_flow
Not supported
Not supported
/batch/send_flow
Not supported
Not supported
/templates/get_template_list
Not supported
Not supported
/collectors/create_collector
Not supported
Not supported
The hierarchy of objects the library can return is
Survey
List<Page>
List<Question>
QuestionType
List<Answer>
List<Item>
List<Collector>
List<Response>
Respondent
List<ResponseQuestion>
List<ResponseAnswer>
Each of these classes has properties which map directly to the names of properties returned by the API itself (though using PascalCasing which is more natural for .NET, rather than the snake_casing used by SurveyMonkey).
For most users, Survey Monkey imposes
a rate limit of 2 requests per second, so by default the library leaves at least 500ms between requests. You can request higher limits from them, so if you want to change the delay between requests just use
a different constructor:
var sm =
new SurveyMonkeyApi(apiKey, token, 200); //200ms delay = 5 reqs per sec
There’s
a separate cap of 1000 requests per day for each API key, which the library doesn’t currently enforce, so if you think you’ll be
in danger of exceeding that you’ll need to handle it yourself for now. To help, you can see how many requests the current instance of the SurveyMonkeyApi object has made by reading its RequestsMade property.
If the library encounters any errors, including communicating with the API, it will throw
a SurveyMonkeyException, so be sure to handle that sensibly any time you use it to make calls.
Finally, if you have
a survey (or list of surveys) obtained using GetSurveyList(), the library can automatically fill
in all available information using
sm.FillMissingSurveyInformation(surveys);
For each survey
in the list, it uses the other endpoints to fill
in the missing information about the survey’s question structure, respondents, and responses. This results
in at least 5 API calls being made per survey, so be careful before passing it
a large list.
It also joins up the raw response information to the survey’s question structure, so that for each question
in a respondent’s set of replies, you can access
a ProcessedAnswer object. For example,
a response to
a dropdown question (from the /surveys/get_responses endpoint) might be represented
in json as
{
"answers": [
{
"row": "9384627365",
}
],
"question_id": "615487516"
}
Separately, the question’s structure (from the /surveys/get_survey_details endpoint) might have several possible answers, one of which might look like
{
"text": "Fourth item
in dropdown list",
"visible": true,
"position": 4,
"type": "row",
"answer_id": "9384627365"
}
The library understands how this mapping works, and uses that to give you the following ProcessedAnswer object, which first describes the family and type of question, and secondly gives you the respondent’s answers as they relate to the question. Survey Monkey has many different question types, with 11 distinct data structures, each of which are supported by the library.
If you have suggestions or spot any bugs, let me know
in the comments, or even better submit
a pull request .
