Add filtering function to Region Device Count API

[chinaunicomyangfan]

Problem description
Based on the discussion in the [issue #8 ], consider adding filtering functionality to the Region Device Count API to obtain more accurate data.
A typical user story: As an advertising advertiser, the filtering function of this API can further segment user status, such as distinguishing between roaming users and non roaming users. For certain advertisements targeting travel or cross-border services, roaming users may be a more attractive target audience. Advertisers can target this group of users with more targeted advertising content, increasing the click through rate and conversion rate of their ads.

Possible evolution
add a filter param to the API
Suggestions for the following dimensions
1.Device Type:human device/IOT device
2.Roaming Status:roamers/all/non-roamers
3.Network standard:2G/3G/4G/5G(This option is not used in the user story above. Record it first and discuss whether there is a need for it)

[gregory1g]

1. It would be fantastic to make filtering syntax extandable, so adding new criteria in the future keeps backward compatibility.
2. I also think that for an API like this, it is ok to allow server to decide what filters to support and issue a error if requested filter is not supported,

[gregory1g]

I did not found any standard/common way to represent filters. Since we do not want to cover really complex logic like (grouping, inversion, "in", "not") we can use something like (inspired by mongodb and some other queries):

"filter": [
"roamingStatus": {"eq", "roaming"},
"connectionType": {"gt", "3G"},
"IoT": { "eq": "no" }
]
where

• all filters are combined with "and" logic.
• "connectionType": {"gt", "3G"} means "4G" or "5G" (parameter specific definition of "greater")

I.e. above filter says that API must return all devices which are here in roaming, connected using 4/5G and are not IoT.

If needed, we can add operations like "in", and grouping like that:
"filter": [
group: {
"roamingStatus": {"eq", "roaming"},
"connectionType": {"in", ["4G", "5G"]},
"operator": "and"
},
group: {
"IoT": { "eq": "no" }
}
"operator": "or"
]

[chinaunicomyangfan]

@gregory1g Thank you for your suggestion.I think our current version does not require overly complex logic, and using the simple filter you mentioned should be able to meet the existing requirements.

"filter": [
"roamingStatus": {"eq", "roaming"},
"connectionType": {"gt", "3G"},
"IoT": { "eq": "no" }
]

Alternatively, because the current enumeration values are limited
1.Device Type:human device/IOT device
2.Roaming Status:roamers/all/non-roamers
3.Network standard:2G/3G/4G/5G
Using the following filtering method may be a simpler approach, but it may lacks scalability.
"filter": [
"roamingStatus": ["roaming"],
"connectionType": ["4G","5G"},
"IoT": ["no"]
]
I.e. above filter says that API must return all devices which are here in roaming, connected using 4/5G and are not IoT.

[gregory1g]

@chinaunicomyangfan , so you suggest a filter which combines all criteria using "AND" and where every single criteria implements "IN" logic:
This looks Ok to me.

[chinaunicomyangfan]

Yes, I think this method is simpler and can meet our current needs. If there are no issues, I am considering adding it to our YAML file.

[hakkiToran]

I think adding filtering capability is a good idea.
We can use the IMSI information to decide whether the user is a Roamer or Not, if the IMSI first digits MNC and MCC information does not belong to the operator, this IMSI should be roamer.

Distinguishing IoT devices just by looking the RAT Connection type may mislead. For Terminal information we can use the TAC code of the IMEI to detect terminal details.
TAC code can be used to detect and filter the terminals. We can know the terminal information and supported technologies using the TAC info.

[chinaunicomyangfan]

@gregory1g @hakkiToran I have added filtering function to the API through the PR. Please check when you have time. Thank you

[hakkiToran]

@chinaunicomyangfan , thank you . I reviewed it. It is OK.