All Products
Search
Document Center

:in_polygon

Last Updated:Jun 12, 2023

Functionality functions

You can use functionality functions in filter clauses to define filter conditions. Functionality functions that return numeric values can be used in sort clauses for sorting.

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

in_polygon: determines whether a point is within a specific polygon geographic area. Generally, this function is used to determine whether a user is within the delivery radius of merchants

1. Syntax

in_polygon(polygon_field, user_x_coordinate, user_y_coordinate, has_multi_polygons="false")

2. Parameters

  • polygon_field: the name of the field that indicates the delivery radius of merchants. The field must be of the DOUBLE_ARRAY type. The field values represent the x- and y-coordinates of the ordered vertices of the delivery polygon. Place the x-coordinate before the y-coordinate. Make sure that the vertices are ordered clockwise or counterclockwise. If N delivery polygons exist, the first value represents the number of delivery polygons. The second value to the (N+1)th value represent the number of vertices of each delivery polygon, not the number of coordinates. The (N+2)th value to the last value represent the x- and y-coordinates of the vertices of each delivery polygon. The value of N ranges from 1 to 50.

image..png
  • user_x_coordinate: the x-coordinate of a user. The value must be of the DOUBLE type.

  • user_y_coordinate: the y-coordinate of a user. The value must be of the DOUBLE type.

  • has_multi_polygons: indicates whether the polygon_field parameter contains multiple independent polygons. The default value is false, which indicates that only one polygon exists.

3. Return value

The number of the polygon that is matched among the N polygons is returned. The return value is of the INT type. If no polygon is matched, 0 is returned.

4. Scenarios

Scenario 1: Determine whether a user is within the delivery radius of merchants. For example, the coordinates field indicates the delivery radius of merchants, and the coordinates of a user are (120.307234, 39.294245). Then, you can use the following query clause to search for merchants that support the delivery radius:

query=default:'Foods'&&filter=in_polygon(coordinates, 120.307234, 39.294245)>0

5. Usage notes

  • The field that you reference in the parameter of the function must be configured as an attribute field.

  • Up to 50 polygons are supported. If the number of polygons exceeds 50, the relevant documents are skipped in the computation.

  • Polygons with holes, such as rings, are not supported.

  • Polygons with multiple separated parts are not supported.

  • If the number of coordinates is 0, no coordinates exist, and 0 is returned.

  • If the number of coordinates is odd, a data error occurs, and 0 is returned.

  • If the user point is located on a side of a specific polygon, the match is considered successful, and 1 or the subscript of the specific polygon is returned.

  • Polygon plug-ins require heavy computational workload, which may affect the query performance. We recommend that you limit the number of vertices. Run tests to determine the number of vertices based on your business requirements.