All Products
Search
Document Center

:distance

Last Updated:Sep 09, 2021

Functions that can be used as both feature functions and functionality functions

Specific functions can be used as both feature functions and functionality functions. You can use such functions in filter clauses, sort clauses, and expressions.

The fields that you reference in parameters of such functions must be configured as index or attribute fields based on the description of each function.

distance: returns the spherical distance between two points Generally, this function is used in distance calculation for a location-based service (LBS).

    1.Syntax:

    distance(longitude_a, latitude_a, longtitude_b, latitude_b, output_name)

    2.Parameters:

    • longitude_a: the longitude value of Point a. The value of this parameter can be the name of a field of the FLOAT type.

    • latitude_a: the latitude value of Point a. The value of this parameter can be the name of a field of the FLOAT type.

    • longtitude_b: the longitude value of Point b. The value of this parameter can be the name of a field of the FLOAT type or a field that is specified in the kvpairs clause in the query string.

    • latitude_b: the latitude value of Point b. The value of this parameter can be the name of a field of the FLOAT type or a field that is specified in the kvpairs clause in the query string.

    • outputname: the return value. This parameter is optional. You can specify this parameter to obtain the calculated distance in the search results.

    3.Return value:

    The distance between Point a and Point b. The return value is of the FLOAT type. Unit: kilometers.

    4.Scenarios:

    Scenario 1: Search for KFCs within 10 kilometers from the coordinates of a user. In this example, the longitude and latitude of the coordinates of the user are 120.34256 and 30.56982. The lon and lat fields that specify the longitude and latitude of a KFC must be configured as attribute fields. The search results are sorted based on a near-to-far order.

    # Use the distance function in a sort clause.
    query=default:'KFC'&&
    filter=distance(lon,lat,"120.34256","30.56982")<10&&
    sort=+distance(lon,lat,"120.34256","30.56982")
    
    # Use the distance function in a fine sort expression.
    Alternatively, you can use the kvpairs clause to pass in the coordinates of the user and use the following fine sort expression to sort the search results by distance: 
    kvpairs=longtitude_in_query:120.34256, latitude_in_query:30.56982
    distance(longitude_in_doc, latitude_in_doc, longtitude_in_query, latitude_in_query, distance_value)

5.Usage notes:

  • The fields that you reference in this function must be configured as attribute fields.

  • The outputname parameter can be used only in fine sort expressions. It cannot be used in a filter or sort clause. If you specify the outputname parameter, the actual distance value is returned in the variableValue node. The variableValue node is returned only when the response format is set to xml or fulljson. You can specify the format in a config clause by setting the format parameter.