I have noticed this on all sorted routes.

The min/max say that they are context sensitive to the sort type yet are documented as date.

How is a date min/max valid when sorting by, for instance votes?


todate and fromdate always refer to creation date.

min and max are with respect to the current sort. So, where sort=votes they place upper and lower bounds on the score of returned answers/questions.

They can overlap, but do not always do so.

Documentation has been updated to reflect that min and max can be of any number of types.

/search for example.

We try and do "what's expected" given a sort value.

sort can be of some set of values depending (and documented on) the route in question. Common values are creation, activity, name, and the like.

Generally, the value of sort corresponds to a field in the returned objects to sort by:

  • creation -> creation_date
  • name -> display_name
  • activity -> last_activity_date
  • and so on...

In rare cases the sorted field is something that is not exposed by the API - generally as a consequence of being hidden on the site, or only shown to logged in user - such as added on users/{id}/favorites.

added sorts returned questions by the date the user in question "favorited" them. As we don't display such information anywhere on the site, its not returned by the API.

While the possible types of min and max is (now) documented, the range can be inferred based on context. Namely, if the field being sorted has a certain range (votes for instance being positive and negative integers, creation_date being >= Jan 1 1970, etc.) then min and max must fall in the same range.

hot, week, and month sorts are strange beasts. The ordering of the returned results is dependent on the "hotness" - an intentionally undocumented algorithm, subject to change, which drives the front page of the sites - of a set of questions. min and max on these sorts restricts questions by last_activity_date. This is something of a compromise. The API can't really take in "hotness" values, since we can't/won't document them, but it we do acknowledge that they are in some way influenced by last_activity_date; so we let you pass those in for a range.

  • Ok, that answers the initial question, which I obviated in the edit. As you say, and as I note, min/max are in respect to sort. If the sort is 'votes', how is a date value for min/max valid? min/max should be specified as string with clarification in the summary. – Sky Sanders Jun 12 '10 at 19:23
  • @code poet - I'm aware of the doc oversight. – Kevin Montrose Jun 13 '10 at 4:39
  • Good. Should I spend time coding around it or just wait for the fix? – Sky Sanders Jun 13 '10 at 10:54
  • @code poet - there are more pressing matters at hand, so it depends how long you're willing to wait. It'll probably be at least a few days. – Kevin Montrose Jun 13 '10 at 11:04
  • No problem. just needed a ballpark. I will compensate for now. – Sky Sanders Jun 13 '10 at 11:49
  • 2
    ummmm... it does not affect me but the incorrectly documented min/max are still confusing people and developers. They should be documented as string and context explained in description – Sky Sanders Jun 27 '10 at 17:32
  • @code poet - this is still scheduled to be fixed, don't worry. Other matters are somewhat more pressing. – Kevin Montrose Jun 27 '10 at 17:56
  • i aint worried, my code is covered. but the top rated library on 'apps' is still calling for int? min/max params - how are other developers going to discover this information. just sayin. – Sky Sanders Jun 27 '10 at 18:01
  • kevin, please take a moment or two and edit this question, stackapps.com/questions/922, so that we developers can make some progress on this front. – Sky Sanders Jun 28 '10 at 18:29
  • are there plans to explain the usage of each sort type? – Sky Sanders Jul 9 '10 at 0:55
  • @code poet - they can be inferred pretty easily I think, but I added some additional explanation to the answer. – Kevin Montrose Jul 9 '10 at 1:23
  • Yes, inference is possible. Easy is a relative term and relying on inference when a brief explanation is possible is not, in my opinion, the best way to publish an API for public consumption. API specification of an API should specify usage, explicitly, to remove guesswork (inference). You have explained the easily inferred sorts, and i appreciate that, but have omitted the less than obvious 'hot', 'month', 'week' etc. Do we need to bracket the target? If sort is 'week' what day is the start of the week? Or are they all the same, simply returning results from the min/max range? – Sky Sanders Jul 9 '10 at 1:35
  • And if they are all the same, e.g. return high activity for a min/max range, what is the purpose of having multiple values? See, I am pretty good at inference but this has been unclear to me from day one, resulting in multiple attempts at getting information. Seems we are making progress. – Sky Sanders Jul 9 '10 at 1:37
  • @code poet - week, hot, and month correspond to the front page sorts. Those aren't documented explicitly because they are subject to change should the front page behavior change. Think of them as "windows" onto the site. The sort is not guaranteed to be stable in those cases though, so its not quite 1 -> 1. Technically the sort isn't stable on the front page either, but due to caching and session magic you get the appearance that they are. – Kevin Montrose Jul 9 '10 at 1:42
  • But you still have not answered the question of how to apply the min/max date params to these sort types. if the behaviour is indeterminant and indescribable what is the purpose of publishing them ? You see, we client library developers do not like to present partial solutions. It leaves a bad taste in the mouth and keeps us up at night. – Sky Sanders Jul 9 '10 at 1:54

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .