Public API v1.0

Now Available!!

Prerequisites

The Public API requires the following:

  1. An understanding of how REST protocol works. There are several online resources available, including Wikipedia and YouTube.
  2. Understanding of the OAuth 2.0 Protocol, specifically the workings of Client Credentials Grant Flow.
  3. A Consumer Key and Consumer Secret registered for the application consuming the APIs. Note that these credentials are different from those you might have had for older APIs. These new credentials give your application full access to only your data.

If you do not have a Consumer Key and/or Consumer Secret, contact Foresee Support.

Endpoints

The following list consists of endpoints which are currently available for beta testing. Click an endpoint to view details of what data is provided:

Please refer to the Glossary of Terms for definitions of acronyms and unfamiliar terms.

Measures

This endpoint returns information about each measure under contract with the client. Each object within the JSON response contains information for an individual ForeSee measure. For example, if you have both a web measure and a mobile measure your JSON response contains two objects.
Settings:

  • https://api.foresee.com/v1/measures
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/Options: None

Properties:

  • id – A unique identifier for the measure which is used in the URL of calls to other various endpoints. The id property is often referred to as the Measure Key.
  • name – The title of the measure, which is generally used as a label in ForeSee web applications and reports.
  • active – Indicates if the measure is currently available to respondents and collecting data.
  • dateCreated – ForeSee internal measure creation date and time stamp in ISO Date Format: YYYY-MM-DDTHH:MM:SS.SSSZZZZZ.
  • factType – Indicates if the measure supports hierarchy organization structure.
  • channel – The type of survey the measure is developed for, such as Web, Store, or Mobile.
  • links – Contains the relationship (rel) and hypertext reference (href) to one or more available endpoints related to the ForeSee measure returned in that object. The href is intended for reference only and not a functioning link. However, some applications, such as Postman, may process this data as a hyperlink which may not work properly.
  • hasMore – This property is for future development. Indicates the returned data is a segment of, and not all of the available data for this end point.

Sample return:

{
  "items": [
    {
      "id": 8840868, 'Measure Key
      "name": "ABC Browse v3",
      "active": true,
      "dateCreated": "2012-03-12",
      "factType": "STANDARD",
      "channel": "WEB",
      "links": [
        {
          "rel": "MEASURE_DEFINITION",
          "href": "/measures/8840868/definition"
        },
        {
          "rel": "MEASURE_DATA",
          "href": "/measures/8840868/data"
        }
      ]
    }
  ]
}

Measure Definition

This endpoint returns the definition or model for a specified measure.

Prerequisites:

Settings:

  • https://api.foresee.com/v1/measures/MEASURE_KEY/definition
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/Options:
    • excludeQuestions – Defaults to False. When set to True, no questions are returned and excludeAnswers is automatically set to True with no answer choices being returned as well.
    • excludeAnswers – Defaults to False. When set to True, no answer choices are returned.

    Example: https://api.foresee.com/v1/measures/MEASURE_KEY/definition?excludeAnswers=”true”

Properties:

  • links – Contains a list of available endpoints related to the ForeSee measure returned in that object.
  • id – A unique identifier for the question.
  • type – Indicates the type of question, usually “MQ” for Measured Question.
  • text – The question text as it is presented to the respondent.
  • phrase – A condensed version of the question text intended for reporting. In some cases, the phrase is intentionally the question text verbatim.
  • answers
    • id – A unique identifier for the answer choice.
    • text – The answer text as it is presented to the respondent.
    • label – The survey label for the answer choice. Example: 1=Poor where “Poor” is the label.
    • value – The numeric value associated with the answer choice. Example: 1=Poor where “1” is the value.

Sample return:

{
  "MQ": [
    {
      "id": "M003703L0004",
      "name": "Look and Feel",
      "type": "ELEMENTS",
      "questions": [
        {
          "id": "ENM003703Q00110",
          "name": "Please rate the visual appeal of this site.",
          "phrase": "Please rate the visual appeal of this site.",
          "type": "MQ",
          "answers": [
            {
              "id": "3784547754",
              "text": "1=Poor",
              "label": "1=Poor",
              "value": 1
            }
          ]
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "/measures/8840868/definition"
    }
  ]
}

Measure Data

This endpoint returns information about each measure under contract with the client. Each object within the JSON response contains information for an individual ForeSee measure. For example, if you have both a web measure and a mobile measure your JSON response contains two objects.

Prerequisites:

Settings:

  • https://api.foresee.com/v1/measures/MEASURE_KEY/data
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/Options:
    • dateRange – Required. Set the start and end dates of responses to limit data to a specific week, month, quarter, etc. See Using Date Criteria for instructions.
    • excludeLatentScores – Defaults to False. Set to True to omit the latentScores property of the response.
    • excludeMQ – Defaults to False. Set to True to omit measured question responses.
    • excludeCQ – Defaults to False. Set to True to omit custom question responses.
    • excludePassedParams – Defaults to False. Set to True to omit Customer Passed Parameters and External Passed Parameters.
    • offset – This refers to a specific page of the paginated data, starting with zero. For example, page 1 is offset 0, page 2 is offset 1, etc. Use offset to request a specific page of data. Paging is a process where data set is broken up into subsets to improve response time since the user is only viewing a portion of the data, i.e., one page of data.
    • limit – This is the number of records per page, with the maximum of 100 records.
    • excludeResponseDetails – Defaults to False. Set to True to omit the responses property.

Properties:

  • hasMore – Indicates the returned data is a segment of, and not all of the available data for this end point.
  • id – The Respondent Identifier assigned to each submitted survey.
  • responseTime – Date and time stamp of when the survey was submitted in ISO Date Format: YYYY-MM-DDTHH:MM:SS.SSSZZZZZ.
  • latentScores- A Latent is group of questions which focus on a particular aspect of the subject being measured. For example, the Look and Feel latent score of a web site is derived from responses to questions concerning the visual aspect, or appearance, of the user interface, such as color scheme or font size.
    • id – A unique identifier used by the system to store and retrieve the latent data.
    • name – The latent label used in reports and for display in web applications.
    • type – A categorization of the latent. For example, the latent Product Images pertains to Elements of what is being measured, e.g., store or web page, where as Likelihood to Return pertains to Future Behavior.
    • score – The overall rating from respondents for the latent.
  • responses
    • id – The response identifier.
    • name – The question text as it is presented to the respondent.
    • phrase – A condensed version of the question text intended for reporting. In some cases, the phrase is intentionally the question text verbatim.
    • type – The type of question, such as Custom Question (CQ) or Model Question.
    • answers – How the respondent replied to the question.

Sample return using the dateRange parameter (required) – https://api-qa.foresee.com/v1/measures/8840868/data?from=2013-08-01&to=2013-08-07:

{
  "hasMore": true,
  "items": [
    {
      "id": "ABC2013234486504",
      "responseTime": "2013-08-01T04:14:00.000Z",
      "latentScores": [
        {
          "id": "M003703L0002",
          "name": "Product Images",
          "type": "ELEMENTS",
          "score": 87.81034581
        }
      ],
      "responses": [
        {
          "id": "ENM003703Q00100",
          "name": "Please rate the number of clicks to get where you want on this site.",
          "phrase": "Please rate the number of clicks to get where you want on this site.",
          "type": "MQ",
          "answers": [
            "9"
          ]
        }
      ]
    }
  ]
}

Sample object using the openEnds endpoint with dateRange and excludeMQ parameters –

Articles in this section:

  1. Using the Public API
  2. Oauth2 Client Credentials Flow