Filtering Athletes

​

Using Custom Query Parameters

The API allows you to include additional query parameters to filter results based on specific attributes, such as team, sport, coach, or any other custom attributes defined in your organization’s data schema. These parameters enable you to narrow down the results to match your specific requirements.

Note: If your organization did not standardize the naming conventions or data, mismatches may occur when filtering athletes. For example, team could be listed as Team, team, or other variations, and xyz could be represented inconsistently (e.g., XYZ, xyz, or Xyz). These discrepancies may lead to incorrect or missing results. Ensure consistent naming conventions for both attribute names and their values to improve filtering accuracy.

​

Examples of Usage

Here are some examples to demonstrate how to use custom attributes effectively:

1. Filter by a Single Attribute
   If you want to retrieve athletes who play a specific sport, use the sport parameter:

   Copy

   curl -X GET 'https://api.uplift.ai/v1/athletes?limit=100&sport=MLB' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json'
   

2. Filter by Multiple Attributes
   You can combine multiple attributes to refine your search further:

   Copy

   curl -X GET 'https://api.uplift.ai/v1/athletes?limit=100&sport=MLB&team=XYZ' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json'
   

3. Sorting Results
   Use the sorted_by parameter to organize the results by a specific field, such as first_name, last_name, or date_of_birth:

   Copy

   curl -X GET 'https://api.uplift.ai/v1/athletes?limit=100&sorted_by=last_name' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json'
   

​

Important Considerations

To ensure the best experience when using custom query parameters, keep the following in mind:

1. Data Availability:
   Custom attributes must exist and be populated in your organization’s data schema. If an attribute is not defined or empty for some records, those records will be excluded from the filtered results.

2. Case Sensitivity:
   Depending on the implementation, some attributes may be case-sensitive. For example, searching for team=XYZ may not return the same results as team=xyz or team=Xyz. Ensure you verify your data structure and consistently use the correct casing, such as uppercase, lowercase, or camel case, based on your data schema.

3. Handling Unexpected Inputs:
   If an attribute value does not match any records, the response will return an empty array. Ensure attribute names and values are spelled correctly to avoid unexpected results.

4. Combining Parameters:
   The API processes query parameters using logical AND. All conditions must match for a record to be included in the results. For example:

   Copy

   ?sport=MLB&team=XYZ&sorted_by=last_name
   

   Only returns athletes who match all specified criteria.

5. Debugging:
   To validate your queries, use smaller limit values (e.g., limit=10) and inspect the response payload to ensure the filtering criteria are applied correctly.