Set Pick Query

Set query options for returning Pick IDs.

Important: The Pick Query is not stored between sessions and must be set before GET query requests (this does not apply to Access Passes.) If not set, a default Pick Query will be used.

NOTE: After setting the initial POST request, a GET can then be used for additional requests.

POST Request URL:

(API)/proxyid/(proxyID)/skipusetoken/(token)/query

Body:

{
    "memberCollectionID": 0,
    "memberIDList": [
        2863529197
    ],
    "howMany": 6,
    "newMixInPercentage": 50,
    "excludeRecentPicksHours": 0,
    "searchOptionList": [
        "RACING",
        "BALANCED",
        "GET_MORE_IF_SHORT"
    ],
    "resultOptionList": [
        "INCLUDE_CATEGORY_INFO",
        "RAMP_NEWEST"
    ],
    "advancedOptionList": [
        "DEBUG_QUERY"
    ],
    "categoryList": [
        "ANY"
    ]
}

Optional, but still a good idea to set these:

memberIDList: optional (MemberIDs, Default=OwnersID): For these Member IDs.

memberCollectionID: optional (MemberID, Default=OwnersID):  The Member's Collection you want to use for searching Picks.

howMany: optional (0-50000, Default= 50000): How many Picks to return.

newMixInPercentage: optional (0-100, Default=0): Try to send back this percentage of new/unused Picks. (lastUpdated == null)

excludeRecentPicksHours: optional (0-8760 hours, Default=0):  Default 0 hours. Set the number of hours to not return recently updated Picks.

Search Options:

searchOptionList: Search for Picks by...

• QUEUE: default: Standard mix of Picks with more Used count and less Skipped. (Additional modifier keyword: RESET. Used to reset the QUEUE search mode if Pick updates from mixed use of other search modes has broken the Pick ordering.)
• BALANCED: Picks are chosen by the count used and the auto-percentage the Pick is expected to be used. Picks are returned by how much they are not in balance.
• RACING: Think of the Tortoise and the Hare story where Picks race to be chosen. The Picks in the lead are chosen. Their speed is determined by the auto-percentage and their track placement by when they were last updated.
• FAVORITE: Picks by highest auto-rating percentage.
• WORST: Picks by lowest auto-rating percentage.
• RANDOM: Picks are chosen randomly weighted by their auto-percentage rating.
• STOP_USING_ONLY: Picks that have been marked for non-use. NOTE: This will ignore some other settings by returning all marked Picks in the current collection.
• PICK_INFO: Return details for just one Pick.

NOTE: you can select two search modes and the two results will be blended together. (See the Result Options)

searchOptionList: Modifiers. (additional ways to modify the search)

• GET_MORE_IF_SHORT: Return Picks even if the other query options can't find the Picks you want. Do not include if you want exact query results.
• USE_TIME_OF_DAY: Search using time of day. This option works well for finding Favorite Picks at the current time of day, where the Picks might not be favorites at a different time of day. NOTE: QUEUE, STOP_USING_ONLY and PICK_INFO search options do not use this option.
• INCLUDE_STOP_USING: If there are Picks marked with the STOP_USING flag, they normally will not be returned. Use this option if you would like to include these Picks in the results.
• ENHANCE: This may provide better Pick results based on what is actively being Skipped and Used; attempting to match Picks with the live trends.
• PERCENT_GREATER_THAN and/or PERCENT_LESS_THAN: Restrict returned Picks to be within a set range of auto-rated percentages.

Result Options:

resultOptionList: key-words to alter the results from from the Search Options.

Order results by the auto-rating percentage:

• RAMP_NONE: default: No ordering.
• RATE_DOWN: Auto-rating percentage from High to Low.
• RAMP_RATE_UP: Auto-rating percentage for Low to High.
• RAMP_OLDEST: Oldest last time stamp updated Picks first.
• RAMP_NEWEST: Newest last time stamp updated Picks first.

Combine results option when using multiple Search options:

• BLEND: default: Combines the 'agreed upon' best results together.
• MERGE: Treats results equally when combining together.

Category metadata in the results:

• INCLUDE_CATEGORY_INFO: Returns any category information associated with the Picks returned. (Slower response time and might cost more because of additional server processing.)

Advanced Options:

Additional options for advance operations.

advancedOptionList: Key-words:

• DEBUG_QUERY: See what is happening with your Pick Query. Returns a detailed message in the JSON result about what settings were used to return the Pick List.
• RESET: Re-orders Picks to work with Search Option QUEUE (if it is no longer returning expected results.) Using non-QUEUE search options can alter the results of the QUEUE search option. Only use this option if you want to use the QUEUE search option but the results are no longer returning expected results from the use of other Search Options. Since this operation reorders ALL the provided member's Picks, this process may take some time. The returned results will not be in the reordered state and a later call will be needed to see notice the results.

Category Options:

Get the Categories that have been marked for return Picks. (Slower response time and might cost more because of additional server processing.)

categoryList: Return picks marked with a category for the selected member. Provide the desired Category names.

Additional modifiers that can be used by adding one keyword to the list:

• ANY: default: Picks will be returned with or without categories.
• NONE: Only Picks with no categories will be returned.
• NOT: Only Picks that do not have the provided categories will be returned.
• PICK_OR: (the default if categories are provided) Return Picks marked with any of the Categories. (not an AND where Picks must be marked with ALL the categories provided)
• EACH_CATEGORY: (coming soon)

NOTE: If more than one provided, choice will limit to just one. Ordering: (ANY > NONE > NOT > EACH_CATEGORY)

NOTE: Remember to set 'INCLUDE_CATEGORY_INFO' in the resultOptionList  if you want to see category information returned.

Other:

Limit Pick results to provided IDs:

pickIDList: You can also limit the result to only return Pick IDs that are in this list.

Important: Pick IDs in this list must already be in the collection or they will be ignored.

Return Only ONE Pick:

pickID:  Set this Pick ID string ONLY if you are searching for ONE Pick with this Pick ID. If a Pick is not stored yet, an empty Pick List will be returned with a the Pick's member ID set to 0.

Response:

{
    "proxyID": "fb736ee8-cb27-4e2d-a30b-a691cb34894d",
    "skipUseToken": "6729592417071498",
    "status": "OK",
    "remainingNibbles": "25",
    "ownerName": "Demo user",
    "ownerID": 3290123131,
    "message": "",
    "pickList": [
        {
            "memberID": 41252,
            "pickID": "possibilities",
            "skipped": 0,
            "used": 3,
            "json": "",
            "stopUsing": false,
            "autoRatePercentage": 87,
            "categoryList": [],
            "searchOrigin": "BY_PICK_INFO",
            "lastUpdated": 1530551309000
        }
    ],
    "followUpRequired": false,
    "validationCodeRequired": false,
    "errorMessage": ""
}