Skip to main content

User Search

Note: This documentation covers User Search specific features. For common concepts like response format, pagination, and general query parameters, see the Getting Started Guide.

Overview​

The Users search endpoint provides a search interface for querying users.

It supports the following types of filtering:

  • Text search: Full-text search on user first names
  • Relationship filtering: Filter by users followed by a specific user, or filter child users (aliases)

Endpoint: GET /v3.0/users/search

Response Format​

Success Response​

Status Code: 200 OK

Response Structure:

{
    "count": 39,
    "next": null,
    "previous": "https://api.getwemap.com/v3.0/users/search?limit=20&query=john",
    "results": [
        {
            "bio": "John's bio",
            "created": "2016-05-21T17:50:27Z",
            "id": 1234567890,
            "firstname": "John",
            "photo_url": "https://api.getwemap.com/images/users/john-profile-photo.jpg",
            "profile_url": null,
            "role": 0,
            "updated": "2023-12-31T08:52:37.330834Z",
            "location": "Paris, France"
        },
        // ... more users
    ]
}

Note: For general response format details (count, next, previous, results fields), see the Getting Started Guide.

Error Responses​

400 Bad Request​

Returned when:

  • No search criteria are provided (at least one criterion is required, except sort_by_name)

Permissions​

The endpoint only returns active users (is_active=True). Inactive or suspended users are excluded from search results.

Query Parameters​

Text Search​

query (string, optional)​

Full-text search on the user's first name.

Searched Fields:

  • User first name

Example:

GET /v3.0/users/search?query=john

Relationship Filtering​

followed_by (integer, optional)​

Filter users that are followed by a specific user. Returns all users that the specified user follows.

Example:

GET /v3.0/users/search?followed_by=42

is_child (boolean, optional)​

Filter child users (aliases) of the authenticated user. If true, returns only child users (aliases) of the authenticated user. If false, returns only non-child users.

Note: This parameter requires authentication. If the user is not authenticated, no users will be returned when is_child=true.

Example:

GET /v3.0/users/search?is_child=true

Sorting​

You can sort the results by relevance score (default sorting) or by first name.

Relevance sorting (default sorting)​

Results are ranked by relevance, which considers:

  • Text match quality: Better matches to your search query are ranked higher

sort_by_name (string, optional)​

Sort results by user first name. Values:

  • asc: Ascending order
  • desc: Descending order

Example:

GET /v3.0/users/search?sort_by_name=asc

Pagination​

For pagination parameters (limit and offset), see the Getting Started Guide.