APIproposal_DeviceVisitLocation_ChinaUnicom.md

Field	Description
API family name	Region User Count
API family owner	China Unicom
Initial API Contributors	Fan Yang - China Unicom , Jin Xu - Huawei
API summary	Description This API allows for the API Consumer to Query the latest visit locations of device within a given time window. The default time window represents the past seven days. Example Use Cases Use Case 1: Anomaly Detection - Role: anti-fraud system . - Goal: As an anti-fraud system, I want to utilize the API to detect anomalies in a user's visited provinces over the past seven days. If a user's visited provinces significantly deviate from their usual pattern or if there are sudden long-distance movements, trigger an alert for further identity verification or security measures. User Story2: Device Location Consistency Check - Role: anti-fraud system - Goal: As an anti-fraud system, I aim to use the API to cross-verify the user's device location with the visited provinces over the past seven days. If there is a notable inconsistency between the user's device location and visited provinces, it may indicate potential fraud. The system should take appropriate actions, such as requesting additional identity verification steps. Input/Output Input MSISDN Output List<geoCode> geoCodeList: Due to the different regional coding methods in different countries and regions, it is difficult to accurately describe provincial information. The parameter composition method proposed in Device Location Verification - Postal/Administrative Code can be used for that end. Specify the area to be verified in a generic way: Use a “geoCode” object having three attributes: “countryCode”: code for the country where the location must be verified. This is necessary because the values of zip codes or administrative codes make sense only for the country where they belong to. “codeType”: the type of code to be used. E.g., “zip”, “adminLevel3”, etc. “codeValue”: value of the code itself. E.g., “75016”, “492755”.
Technical viability	This API is based on real-time location information expansion, recording changes in base stations, and querying user visits based on the location of base stations. The operator needs to record XDR signalling continously, and store it for the selected time window, because the operator does not know if/when this information will be requested by the API consumer.
Commercial viability	For use in anti fraud and precision marketing scenarios
YAML code available?	NO To be provided
Validated in lab/productive environments?	YES Available in China UniCom test environment
Validated with real customers?	YES For anti fraud use by National Police System
Validated with operators?	YES Available for China Unicom in China
Supporters in API Backlog Working Group	China Unicom