Public API (deprecated) - Endpoints

Endpoints

Respondent Data:
Using Date Criteria Calendar Endpoints
Measures Latents
Questions Answer Choices
Model Filters Page Filters
Respondent Extract Endpoint
Channels Current User
Status Version
Aggregate Data:
Scores Scores By Answer
Open Ends Latent Trend
Scores By Answer Trend Super Latents
Benchmark Categories Client Names
Benchmark Scores Combined Scores
Combined Scores – Scores and Weight Combined Scores – Trend

Using Date Criteria

Here are some examples of using Date Criteria. Refer to the Date Resolution Table for parameters and variables.

  • A simple To and From using “f” and “l” (first and last):
    Example: https://services.foresee.com/services/calendar/lookup?criteria={“dateRange”:{“f”:”2014-07-01″,”l”:”2014-07-02″}}

    Use To and From when you want data during a specific time frame, such as a holiday season.

  • Rolling one day always returns the previous day:
    Example: https://services.foresee.com/services/calendar/lookup?criteria={“dateRange”:{“r”:”D”,”n”:”1″}}

    Use Rolling Day to use the same call on a daily basis, instead of using the previous To and From, which would require edits each day.

  • Rolling one month always returns the previous full month:
    Example: https://services.foresee.com/services/calendar/lookup?criteria={“dateRange”:{“r”:”M”,”n”:”1″}}

    Use Rolling Month to use the same call on a monthly basis, instead of using the previous To and From, which would require edits each month.

Calendar Endpoints

The available endpoints are:

  • types – To see the available variables for the Calendar Type parameter as described in the Date Resolution Table.
    Example: https://services.foresee.com/services/calendar/types

    [
        "GREGORIAN",
        "FISCAL"
    ]
  • ranges – To see the available variables for the Range parameter as described in the Date Resolution Table.
    Example: https://services.foresee.com/services/calendar/ranges

    [
       "DAY",
       "WEEK",
       "MONTH",
       "QUARTER",
       "YEAR",
       "DAYS",
       "WEEKS",
       "MONTHS",
       "QUARTERS",
       "YEARS",
       "CUSTOM"
    ]
  • periods – To see the available variables for the Period parameter as described in the Date Resolution Table.
    Example: https://services.foresee.com/services/calendar/periods/types

    [
        "DEFINED",
        "PRIOR",
        "CURRENT",
        "NEXT",
        "YEAR"
    ]
  • lookup – To see date parameters (see Using Date Criteria).
    Example: https://services.foresee.com/services/calendar/lookup

    {
       "k": null,
       "c": "GREGORIAN",
       "r": "CUSTOM",
       "p": "DEFINED",
       "n": 0,
       "f": "2016-07-29",
       "l": "2016-07-29",
       "vndType": "application/vnd.foresee.date.range"
    }

The following list consists of endpoints currently available and brief descriptions of what each provides.

Measures

  • https://services.foresee.com/services/clients/CLIENTID/measures
  • This endpoint returns information about each measure the API account has access to.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: None
  • 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.
  • Properties:
    • links – Contains a list of available endpoints related to the ForeSee measure returned in that object.
    • measurementKey – The measure identifier which is used in the URL of calls to other various endpoints.
    • name – The title of the measure.
    • modelInstanceId – ForeSee internal model instance identifier.
    • channelIdentifier – ForeSee internal channel title.
    • channelType – ForeSee internal channel identifier.
    • createDate – ForeSee internal measure creation date.
    • currentlyActive – Indicates if the measure is currently active. 1 = Active, 0 = Inactive
    • clientId – Client identifier used in the URL of other calls.
    • vndType – Identifies the object associated with this response.

    Sample object:

    {
        "links": [
            {
                "rel": "self",
                "href": "https://services.foresee.com/services/
                    clients/12345678/measures/9999999"
            },
            {
                "rel": "questions",
                "href": "https://services.foresee.com/services/
                    clients/12345678/measures/9999999/questions"
            },
            {
                "rel": "latents",
                "href": "https://services.foresee.com/services/
                    clients/12345678/measures/9999999/latents"
            },
            {
                "rel": "modelFilters",
                "href": "https://services.foresee.com/services/
                    clients/12345678/measures/9999999/modelfilters"
            },
            {
                "rel": "pageFilters",
                "href": "https://services.foresee.com/services/
                    clients/12345678/measures/9999999/pagefilters"
            },
        ],
        "measurementKey": 8840868,
        "name": "ABC Browse v3",
        "modelInstanceId": "9VxNxdYdJwoo0oggJ5EdFg==",
        "channelIdentifier": "WEB",
        "channelType": 1,
        "createDate": "2012-03-12",
        "currentlyActive": 1,
        "clientId": 418144,
        "vndType": "application/vnd.foresee.measure"
    },
    

Latents

  • https://services.foresee.com/services/clients/CLIENTID/measures/MEASUREID/latents
  • This endpoint returns all latents for the selected measure
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: None
  • Each model element is represented as an object within the JSON response for the Latents endpoint.
  • Properties:
    • latentKey – The unique identifier for the latent.
    • name – The name of the latent.
    • latentType – The classification of latent.
    • latentTypeId – The latent type identifier.
    • modelLatentId – The unique model latent identifier for the latent.
    • vndType – Identifies the object associated with this response.
    • links – A list of links available for the latent returned in that object.

    Sample object:

    {
        "latentKey": 89940398,
        "name": "Look and Feel",
        "latentType": "Element",
        "latentTypeId": 1,
        "modelLatentId": "M003703L0004",
        "vndType": "application/vnd.foresee.latent",
        "links": [
            {
                "rel": "self",
                "href": "https://services.foresee.com/services/
                clients/12345678/measures/9999999/latents/89940398"
            }
        ]
    }
    
    

Questions

  • https://services.foresee.com/services/clients/CLIENTID/measures/MEASUREID/questions
  • This endpoint returns all questions for the selected measure
  • Available Parameters/ Options:
    • dateRange – Not required
  • Every question from the selected measure is represented as in object within the JSON response from the Questions endpoint.
  • Properties:
    • links – A list of endpoints available for the question returned in the object.
    • questionKey – The unique identifier for the question. This key is used in calls to other endpoints.
    • questionId – The unique identifier of the question.
    • questionType – The type of question.
    • questionTypeKey – The key for the type of question.
    • questionTypeId – The ID for the type of question.
    • respTypeId – The response type ID.
    • label – The short label for the question.
    • text – The question text.
    • phrase – A condensed version of the question text intended for reporting. In some cases, the phrase is intentionally the question text verbatim.
    • latentKey
      • The latent key the question is connected with.
      • Only present for model questions.
    • vndType – Identifies the object associated with this response.

    Sample object:

    {
        "links": [
            {
                "rel": "self",
                "href": "https://services.foresee.com/services/
                clients/12345678/measures/9999999/questions/551070759"
            },
            {
                "rel": "answers",
                "href": "https://services.foresee.com/services/
                clients/12345678/measures/9999999/
                questions/551070759/answers"
            }
        ],
        "questionKey": 551070759,
        "questionId": "ENM003703Q00110",
        "questionType": "Measured Question",
        "questionTypeKey": "MQ",
        "questionTypeId": 0,
        "respTypeId": 9999,
        "label": "Look and Feel - Appeal",
        "text": "Please rate the visual appeal of this site.",
        "phrase": "Please rate the visual appeal of this site.",
        "latentKey": 89940398,
        "vndType": "application/vnd.foresee.question"
    }
    

Answer Choices

  • …/services/clients/CLIENTID/questions/QUESTIONKEY/answers
  • This endpoint returns all answer choices for the selected question
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: None
  • Every answer choice for the selected question is represented as an object with the JSON response for the Answer Choices endpoint.
  • Properties:
    • links – A list of endpoints available for the answer choice returned in the object.
    • answerKey – A unique identifier for the answer choice.
    • value – The actual value associated with the answer choice.
    • label – The survey label for the answer choice.
    • text – The actual text for the answer choice.
    • displayLabel – The display label for the answer choice.
    • vndType – Identifies the object associated with this response.

    Sample object:

    {
        "links": [
            {
                "rel": "self",
                "href": "https://services.foresee.com/services/
                clients/12345678/measures/9999999/questions/551070759/
                answers/3784547754"
            }
        ],
        "answerKey": 3784547754,
        "value": 1,
        "label": "1=Poor",
        "text": "1=Poor",
        "displayLabel": "1=Poor",
        "vndType": "application/vnd.foresee.answer"
    }
    

Model Filters

  • https://services.foresee.com/services/clients/CLIENTID/measures/MEASUREID/modelfilters
  • This endpoint lists all model filters that have been created and saved in the portal
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: None
  • Every model filter saved in the ForeSee Advanced Analytics Portal is represented as object within the JSON response for the Model Filters endpoint.
  • Properties:
    • links – A list of endpoints available for the model filter returned in the object.
    • modelFilterId – The unique ID of the model filter.
    • name – The saved name of the model filter.
    • vndType – Identifies the object associated with this response.
    • encryptedModelFilterId – ForeSee internal use only.

    Sample Object:

    {
        "links": [
            {
                "rel": "self",
                "href": "https://services.foresee.com/services/
                    clients/12345678/measures/9999999/modelfilters"
            }
        ],
        "modelFilterId": 327557,
        "name": "Filter: Primary Purpose - Just Browsing",
        "vndType": "application/vnd.foresee.modelfilter",
        "encryptedModelFilterId": "pWuEczDmI6AtnJCK%2F5rhdQ%3D%3D%0D%0A"
    }
    

Page Filters

  • https://services.foresee.com/services/clients/CLIENTID/measures/MEASUREID/pagefilters
  • This endpoint lists all page filters that have been created and saved in the portal
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: None
  • Every page filter saved in the ForeSee Advanced Analytics Portal is represented as object within the JSON response for the Page Filters endpoint.
  • Properties:
    • links – A list of endpoints available for the model filter returned in the object.
    • pageFilterId – The unique ID of the page filter.
    • name – The saved name of the page filter.
    • vndType – Identifies the object associated with this response.

    Sample Object:

    {
        "links": [
            {
                "rel": "self",
                "href": "https://services.foresee.com/services/
                    clients/12345678/measures/9999999/pagefilters"
            }
        ],
        "pageFilterId": 12381,
        "name": "register-product-1",
        "vndType": "application/vnd.foresee.pagefilter"
    }
    

Respondent Extract

    • …/services/clients/CLIENTID/measures/MEASUREID/respondentsextract
    • This endpoint returns raw respondent level data for the selected time period and questions. This endpoint requires a POST call to supply the criteria and queue the report for processing. A GET call is then made to retrieve the resulting report once it is ready.
    • HTTP Method: POST followed by GET
    • Available Parameters/ Options:
      • dateRange
      • questionKey
    • POST Properties:
      • reportId – A system generated unique identifier required for the GET call.
      • reportStatus – The current progress of the report generation.
      • submittedTime – A date and time stamp of the POST call.
      • reportURL – The full address link for the GET call.
      • vndType – Identifies the object associated with this response.

Sample object of a POST call:

{
    "reportId": 5461,
    "reportStatus": "PENDING",
    "submittedTime": "2014-07-29T10:52:56.008",
    "reportURL": "https://services.foresee.com/services/
         clients/12345678/measures/9999999/
         respondentsextract?reportId=5461",
    "vndType": "application/vnd.foresee.queuedreport"
}
  • GET Properties – When GET is invoked before the report has completed, the system returns “status”: 202 with the following properties:
    • reportID – A system generated, unique identifier.
    • reportStatus – “PROCESSING”
    • dateTime – A time stamp of when the Get was attempted. Format is YYYY-MM-DDTHH:MM:SS.SSS.
    • vndType – Identifies the object associated with this response.

    When GET is successful, the system returns “status”: 200 with the following properties:

    • The measure identifier which is used in the URL of calls to other various endpoints.
    • criteria – The parameters used to generate the report.
    • results – A list of respondent data:
      • respondentID – A system generated unique identifier.
      • respnseDate – The date of when the survey was completed in the format of YYYY-MM-DD.
      • reponseTime – A time stamp of when the survey was completed in the format of HH:MM:SS.
      • latentScores – Returns the identifier and score for all latents.
      • responses – Returns the question identifier and answer for all selected questions.
    • vndType – Identifies the object associated with this response.

    Sample object of a GET call:

        "results": [
            {
                "respondentId": "0wApx0gBosVxZVtkA08Icg4C",
                "responseDate": "2014-07-24",
                "responseTime": "14:24:46",
                "latentScores": [
                    {
                        "l": 987654321,
                        "s": 75.99999
                    }
                ],
                "responses": [
                    {
                        "q": 11111111,
                        "a": "answer 1"
                    },
                    {
                        "q": 22222222,
                        "a": "answer 2"
                    }
                ]
            }
        ],
    

Endpoint

  • https://services.foresee.com/services/endpoints
  • This endpoint returns information about the current user account, all ForeSee portal authorities and the endpoints this account has access to.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: NoneSample Object:
    {
        "vndType": "application/vnd.foresee.services.endpoints",
        "currentUser": {
            "userId": 12345,
            "username": "api.test.user",
            "firstName": "API",
            "lastName": "User",
            "clientId": 12345,
            "grantedAuthorities": [
                {
                    "authority": "ADHOC"
                },
                {
                    "authority": "ADVANCED_ANALYTICS"
                }
            ]
        },
        "list": [
            {
                "endpoint": "GET /calendar"
            },
            {
                "endpoint": "GET /clients/{clientId}/measures/
    			{measurementKey}/questions",
                "roles": [
                    "API_TIER_1"
                ]
            },
            {
                "endpoint": "POST /clients/{clientId}/measures/
    			{measurementKey}/respondentsextract?[criteria]",
                "roles": [
                    " API_TIER_1"
                ]
            },
                "links": [
            {
                "rel": "self",
                "href": "https://services.foresee.com/services/
                         endpoints"
            }
        ]
    }
    

Channels

  • https://services.foresee.com/services/channels
  • This endpoint returns the ForeSee internal name and ID for the various channels of measurement offered by ForeSee.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: NoneSample Object:
    [
        {
            "identifier": "WEB",
            "channelType": 1,
            "description": "Web"
        },
        {
            "identifier": "STORE",
            "channelType": 2,
            "description": "Store"
        }
    ]

Current User

  • https://services.foresee.com/services/currentUser
  • This endpoint returns information and ForeSee portal credentials for the current user account.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: NoneSample Response:
    {
        "links": [
            {
                "rel": "self",
                "href": "https://services.foresee.com/services/
    				currentUser"
            },
            {
                "rel": "user",
                "href": "https://services.foresee.com/services/
    				clients/-1/users/38229"
            },
            {
                "rel": "client",
                "href": "https://services.foresee.com/services/
    				clients/-1"
            }
        ],
            "userId": 12345,
            "username": "api.test.user",
            "firstName": "API",
            "lastName": "User",
            "clientId": 12345,
            "grantedAuthorities": [
                {
                    "authority": "ADHOC"
                },
                {
                    "authority": "ADVANCED_ANALYTICS"
                }
        ]
    }

Status

  • https://services.foresee.com/services/status
  • This endpoint returns internal ForeSee information about the current service status.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: NoneSampe Response:
    {
        "result": "OK",
        "status": "UP",
        "location": "PRIMARY",
        "statusMessage": "",
        "dataSource": "java:jboss/datasources/foreSeeServices",
        "heartbeat": "select 1 from dual",
        "locationSource": "foresee.services.location",
        "timestamp": "2014-07-28T13:37:38.480"
    }

Version

  • https://services.foresee.com/services/version
  • This endpoint returns internal ForeSee information about the current version of the application.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: NoneSample Response:
    {
        "name": "ForeSee Services",
        "build": "FORESEE_SERVICES-RC-build-deploy-stg",
        "version": "2.0.7-40",
        "revision": "37776",
        "buildDate": "2014-07-25_09-27-01",
        "vndType": "application/vnd.foresee.services.version"
    }

Aggregate Data

The following endpoints return the aggregated data endpoints that can be used by clients to build internal dashboards based on ForeSee data:

NOTE: These calls are for a specific clientID, i.e., https://services.foresee.com/services/clients/CLIENTID…

Scores

  • …/measures/MEASUREID/scores
  • This endpoint is used to get aggregated Element, Satisfaction, and Future Behaviors scores for a specified date range. Typical options applied to this call include a specific date range, model filter, page filter and/or hierarchy filter.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options:
    • dateRange – required
    • dateRangeComparison
    • modelFilter
    • pageFilter
    • hierarchyFilter
    • userFilter
  • Each object within the JSON response contains information for an individual ForeSee latent.Sample object:
    {
    	"latentKey": 89940398,
    	"latentType": "Element",
    	"latentName": "Look and Feel",
    	"score": 88.50099
    }
    

Scores By Answer

  • …/measures/MEASUREID/questions/QUESTIONKEY/scoresbyanswer
  • This endpoint is used to get the latent score, percentage, and n count for each answer choice for the selected question and latentKey.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options:
    • dateRange – Not required
  • Each object within the JSON response contains information for an individual ForeSee answerKey.Sample object:
    {
    	"answerKey": 3784547754,
    	"answerLabel": "1=Poor",
    	"score": null,
    	"answerPercentage": 0,
    	"n": 0
    }
    

Open Ends

  • …/measures/MEASUREID/openends
  • This endpoint is used to get open-end comments for the selected measure and time period.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options:
    • dateRange – required
    • commentKeys – required, use /measures/MEASUREID/commentquestions to get a list of qkey values.
    • pageRequest
    • textFilter
    • questionKeys
    • latentKeys

    Sample object for …/openends?criteria={“dateRange”:{“f”:”2012-10-01″,”l”:”2012-10-31″}, “commentKeys”:[550999858]}:

    {
        "respondentKey": 210944009,
        "responseDate": "2012-10-31",
        "comments": [
        {
        "qKey": 550999858,
        "a": "Have more outfit ideas/pictures of models wearing complete outfits."
        }
        ],
        "answers": [],
        "scores": []
        }
    

Latent Trend

  • …/measures/MEASUREID/atents/LATENTKEY/trend
  • This endpoint is used to get trended latent scores for selected latent and date range.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options:
    • dateRange – required
    • dateRangeComparison
    • modelFilter
    • pageFilter
    • hierarchyFilter
    • userFilter

    Sample Response:

    {
        "d": "2012-10-01",
        "v": 90.52826
    }

Scores By Answer Trend

  • …/measures/MEASUREID/questions/QUESTIONKEY/scoresbyanswertrend
  • This endpoint is used to get score and distributions trends for a selected answer and latent.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options:
    • dateRange – Not required

    Sample Response:

    {
        "answerKey": 3784547754,
        "answerLabel": "1=Poor",
        "score": null,
        "answerPercentage": 0,
        "n": 0
    }

Super Latents

  • …/measures/MEASUREID/slatents
  • This endpoint returns a list of super latents and super latent keys that are used when getting benchmark scores.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: NoneSample Response:
    {
        "name": "Look and Feel",
        "slatentKey": 63,
        "links": [
            {
                "rel": "benchmarkCategories",
                "href": "https://.../slatents/63/bmcat"
            },
            {
                "rel": "benchmarkCategoryGroups",
                "href": "https://.../slatents/63/bmcatgroups"
            }
        ]
    }

Benchmark Categories

  • …/measures/MEASUREID/slatents/SLKEY/bmcat
  • This endpoint provides a list of benchmark categories available for the selected Super Latent key.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: NoneSample Response:
    {
        "key": 232,
        "links": [
            {
                "rel": "details",
                "href": "https://...slatents/63/bmcat/232/details"
            }
        ],
        "desc": "Academic Medical Centers",
        "measCat": false
    }

Client Names

  • …/measures/MEASUREID/slatents/SLKEY/bmcat/BMCATKEY/details
  • This endpoint provides a list client names that are included in the selected super latent and benchmark category.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options:
    • dateRange – Not required

    Sample Response:

    {
        "name": "Client XYZ"
    }

Benchmark Scores

  • …/measures/MEASUREID/benchmarkscores
  • This endpoint is used to get benchmark scores for a selected super latent and category.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options:
    • dateRange – required
    • superLatentKey – required, use …/measures/MEASUREID/slatents/SLKEY/bmcat for a list of slatentKey values.
    • bmCatKeys

    Sample Response:

    {
        "key": 232,
        "desc": "Academic Medical Centers",
        "cnt": 6,
        "min": 76,
        "avg": 80,
        "max": 84,
        "q1": null,
        "q2": null,
        "q3": null,
        "dayAvail": 1,
        "complete": true    
    }

Combined Scores

  • …/CLIENTID/combinedscores
  • This endpoint is used to get a list of all combined scores for the current client.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options: NoneSample Response:
    {
        links": [
            {
                "rel": "scores",
                "href": "https://.../combinedscores/1581/scores"
            },
            {
                "rel": "latentScores",
                "href": "https://.../combinedscores/1581/latentscores"
            },
            {
                "rel": "trend",
                "href": "https://.../combinedscores/1581/trend"
            }
        ],
        "combinedScoreKey": 1581,
        "name": "Browse_InStore_Byrespondent",
        "description": null,
        "weightMethod": "RESPONDENT",
        "multiChannel": true,
        "vndType": "application/vnd.foresee.combinedscore" 
    }

Combined Score – Scores and Weight

  • …/CLIENTID/combinedscores/COMBINEDSCOREKEY/scores
  • This endpoint is used to get the combined score and component scores and weights for the selected combined score. This endpoint also provides the componentKey which is used in the Combined Score – Trend endpoint.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options:
    • dateRange – required

    Sample Response:

    {
        "combinedScoreKey": 1581,
        "name": "Browse_InStore_Byrespondent",
        "type": "COMBINED_SCORE",
        "weight": 100,
        "score": 86.63469,
        "n": 4269,
        "subScores": [
            {
                "componentKey": 3575,
                "name": "ABC Browse v3 - Look and Feel (Unfiltered)",
                "type": "ELEMENT_LATENT",
                "weight": 16,
                "score": 88.50099,
                "n": 4089,
                "weightMethod": "RESPONDENT"
            }    
    }

Combined Score – Trend

  • …/combinedscores/COMBINEDSCOREKEY/trend
  • This endpoint is used to get trend scores and weights for an individual component of a combined score.
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/ Options:
    • dateRange – required
    • componentKey – use …/CLIENTID/combinedscores/COMBINEDSCOREKEY/scores for a list of componentKey values.

    Sample object:

    {
        "scores": [
            "d": "2012-10-25",
            "v": 88.41318
        }
        ],
        "weights": null,
        "vndType": "application/vnd.foresee.combinedscore.trend.result"
    }
    

Other articles in this section:

  1. OAuth Protocol
  2. Date Resolution
  3. Endpoints (current article)
  4. Glossary of Terms