What is the right way to create a Stack Exchange API filter?

Question

I'm trying to create a filter by following the documentation, but a few things are quite unclear:

1. How do I create a filter that does not have a base filter?

2. I'm creating a filter without a base so I can only fetch certain fields, but the responses have no data at all. What am I doing wrong?

3. I'm trying to include or exclude multiple fields in a filter. What's the delimiter?

Answer 1

I have experimentally determined that:

1. The base parameter must be passed a value of none to create a filter without a base.

2. Fields in the default wrapper object can be filtered; you must include .items in your filter to receive any data from inside it. (The base filter does; this is why filters with a base don't have this problem.)

3. This is technically a vector parameter; so, as with all vectors in the API, the delimiter is ; (U+0003B SEMICOLON).

Answer 2

I have struggled with Stack Exchange API filters too, when I tried to incorporate up_vote_count, down_vote_count and view_count attributes in my user response object.

I visited this page of the Stack Exchange API to create my filter (same as you). I just wanted to include my three attributes and thus set the following parameters:

include: user.up_vote_count;user.down_vote_count;user.view_count
exclude: <left empty>
base: <left empty>
unsafe: false

That created my desired response (I have shortened the code below to save some space):

{
  "items": [
    {
      "included_fields": [
        ".backoff",
        ".error_id",
        ".error_message",
        ".error_name",
        ".has_more",
        ".items",
        ".quota_max",
        ".quota_remaining",
        "access_token.access_token",
        "access_token.account_id",
        "access_token.expires_on_date",
        "access_token.scope",
        "account_merge.merge_date",
        "account_merge.new_account_id",
        "account_merge.old_account_id",
        ...
        "user.accept_rate",
        "user.account_id",
        "user.age",
        "user.badge_counts",
        "user.creation_date",
        "user.display_name",
        "user.down_vote_count",
        "user.is_employee",
        "user.last_access_date",
        "user.last_modified_date",
        "user.link",
        "user.location",
        "user.profile_image",
        "user.reputation",
        "user.reputation_change_day",
        "user.reputation_change_month",
        "user.reputation_change_quarter",
        "user.reputation_change_week",
        "user.reputation_change_year",
        "user.timed_penalty_date",
        "user.up_vote_count",
        "user.user_id",
        "user.user_type",
        "user.view_count",
        "user.website_url",
        "user_timeline.badge_id",
        "user_timeline.comment_id",
        "user_timeline.creation_date",
        "user_timeline.detail",
        "user_timeline.post_id",
        "user_timeline.post_type",
        "user_timeline.suggested_edit_id",
        "user_timeline.timeline_type",
        "user_timeline.title",
        "user_timeline.user_id",
        "write_permission.can_add",
        "write_permission.can_delete",
        "write_permission.can_edit",
        "write_permission.max_daily_actions",
        "write_permission.min_seconds_between_actions",
        "write_permission.object_type",
        "write_permission.user_id"
      ],
      "filter_type": "safe",
      "filter": "!-*f(6q9Y*ecs"
    }
  ],
  "has_more": false,
  "quota_max": 10000,
  "quota_remaining": 9989
}

I have written down the filter value

!-*f(6q9Y*ecs

and used that as a parameter when fetching the user object (in my case I used the py-stackexchange wrapper):

so_user_obj = so.user(so_user_id, filter='!-*f(6q9Y*ecs')

It worked like a charm.

So, to answer your questions:

1. As shown above
2. As shown above
3. Semicolon worked for me.

HTH, André