Suggestion type:
New feature request
What needs to be done:
Add a new selection to the User endpoint (/user/?selections=honors) that provides comprehensive honors progress data, including all honors (regardless of completion status), current progress for each honor, completion status, honor category information, and optional filtering by status and category.
The endpoint should support optional parameters:
status (optional): Filter by completion status (completed, in_progress, not_started, all). Default: all honors.category (optional): Filter by honor category. Categories include: Crime, Education, Faction, Item, Medical, Miscellaneous, Money, Personal, Racing, Social, Travel, War. Default: all categories.
Why do you need this:
Currently, there is no way to programmatically track honor progress through the API. This limits users' ability to:
- Create community tools, dashboards, leaderboards to track their honor progress and identify which honors are close to completion
- Calculate total available merits from uncompleted honors for strategic planning
- Analyze progress by category to identify which areas need more attention
- Easily plan which honors to focus on next based on progress and merit rewards
Without this feature, users who want to track their honor progress must either manually check the in-game Awards page or resort to page scraping, which potentially violates ToS. Having this data available through the API would enable ToS-compliant community tools and enhance the overall user experience.
Consider any drawbacks of your suggestion:
The primary concern is ensuring this feature does not provide an unfair advantage. However, honor progress is already visible to users in-game on the Awards page, so making this data available via API simply provides programmatic access to information that is already publicly accessible to the API key owner. This maintains parity with in-game functionality rather than providing new information.
Client-side optimization strategies (for script developers):
- Rate limiting awareness: Honor progress doesn't change frequently, so scripts should cache responses locally and respect the 100 req/min limit. Recommended polling intervals of 5-15 minutes minimum for honor tracking scripts.
- Selective requests: Scripts should use filters (
status, category) to request only needed data rather than full honor lists when possible. For example, if only tracking in-progress honors, use status=in_progress instead of fetching all honors.
- Delta update adoption: If a
since parameter is implemented, scripts should use it for incremental updates rather than full refreshes. Store the last update timestamp and only request changes since that time.
- Field minimization: If a
fields parameter is implemented, scripts should request only required fields to minimize payload size and processing time. Most tracking scripts only need honor_id, progress, and completed.
- Local caching: Scripts should implement local caching with appropriate TTLs. Honor definitions are static and can be cached indefinitely, while progress can be cached for several minutes.
- Batch processing: When updating multiple honors, scripts should batch operations and avoid making individual requests for each honor.
- Error handling: Scripts should implement proper error handling for rate limits (429) and retry with exponential backoff rather than hammering the API.
Response size considerations:
- The response could be large if returning all honors at once, but filtering by status and category helps reduce response size when users only need specific subsets.
- Honors progress updates in real-time, so scripts need to balance freshness with API usage. Most use cases don't require real-time updates.
No competitive advantage concerns:
This feature provides the same information available in-game, just in a programmatic format that enables tool development and better user experience.
Example Default response (all honors, no filters):
{
"honors": [
{
"honor_id": 12345,
"name": "Crime Master",
"description": "Complete 200 crimes",
"category": "Crime",
"completed": false,
"progress": {
"current": 150,
"total": 200,
"percentage": 75.0
},
"requirements": {
"type": "numeric",
"description": "Complete 200 crimes"
},
"reward": {
"merits": 5,
"points": 0
}
},
{
"honor_id": 12346,
"name": "Educated",
"description": "Complete 100 courses",
"category": "Education",
"completed": true,
"progress": {
"current": 100,
"total": 100,
"percentage": 100.0
},
"requirements": {
"type": "numeric",
"description": "Complete 100 courses"
},
"reward": {
"merits": 3,
"points": 0
},
"completed_date": 1234567890
},
{
"honor_id": 12347,
"name": "World Traveler",
"description": "Visit 50 countries",
"category": "Travel",
"completed": false,
"progress": {
"current": 0,
"total": 50,
"percentage": 0.0
},
"requirements": {
"type": "numeric",
"description": "Visit 50 countries"
},
"reward": {
"merits": 2,
"points": 0
}
}
],
"summary": {
"total": 150,
"completed": 45,
"in_progress": 60,
"not_started": 45,
"total_merits_earned": 225,
"total_merits_available": 450
}
}
Filtered response (status=in_progress):
{
"honors": [
{
"honor_id": 12345,
"name": "Crime Master",
"description": "Complete 200 crimes",
"category": "Crime",
"completed": false,
"progress": {
"current": 150,
"total": 200,
"percentage": 75.0
},
"requirements": {
"type": "numeric",
"description": "Complete 200 crimes"
},
"reward": {
"merits": 5,
"points": 0
}
}
],
"summary": {
"total": 60,
"completed": 0,
"in_progress": 60,
"not_started": 0,
"total_merits_earned": 0,
"total_merits_available": 300
},
"filters_applied": {
"status": "in_progress"
}
}
Filtered response (category=Crime, status=in_progress):
{
"honors": [
{
"honor_id": 12345,
"name": "Crime Master",
"description": "Complete 200 crimes",
"category": "Crime",
"completed": false,
"progress": {
"current": 150,
"total": 200,
"percentage": 75.0
},
"requirements": {
"type": "numeric",
"description": "Complete 200 crimes"
},
"reward": {
"merits": 5,
"points": 0
}
}
],
"summary": {
"total": 12,
"completed": 0,
"in_progress": 12,
"not_started": 0,
"total_merits_earned": 0,
"total_merits_available": 60
},
"filters_applied": {
"category": "Crime",
"status": "in_progress"
}
}
Example API calls:
/user/?selections=honors&key=YOUR_API_KEY (all honors)/user/?selections=honors&status=in_progress&key=YOUR_API_KEY (only in-progress honors)/user/?selections=honors&category=Crime&key=YOUR_API_KEY (only Crime category honors)/user/?selections=honors&category=Crime&status=completed&key=YOUR_API_KEY (completed Crime honors)
Thanks for taking the time to review this novel...I know it took a while to read, at least not as long as it took me to write. -_-
edit: also, yall should add code blocks in forum posts...that was brutal.
![[image: design-ninja.net]](https://design-ninja.net/img/torn/valentines-day-lotto/svd_lotto.jpg){kind=link}