Skip to main content

List Search

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

Overview​

The Lists search endpoint provides a search interface for querying lists (collections of pinpoints).

It supports the following types of filtering:

  • Text search: Full-text search on list names, descriptions, and addresses
  • Collection filtering: Filter by livemaps, pinpoints (lists containing a specific pinpoint), portals, or users
  • Tag filtering: Filter by tags with support for AND/OR logic
  • Attribute filtering: Filter by list type, itinerary status, contributive status, and liked by users

Endpoint: GET /v3.0/lists/search

Response Format​

Success Response​

Status Code: 200 OK

Response Structure:

{
  "count": 1234,
  "next": "https://api.getwemap.com/v3.0/lists/search?limit=20&offset=20&query=list+name",
  "previous": null,
  "results": [
      {
          "author": {
              "name": "Author name",
              "photo_url": "https://api.getwemap.com/images/users/author-profile-photo.jpg"
          },
          "created": "2023-12-04T13:06:07.695504Z",
          "description": "List description",
          "external_data": null,
          "id": 456,
          "image_url": "https://api.getwemap.com/images/pps-lispoints/245b6e39eb408c48a6544eab.94668809.jpg",
          "is_contributive": false,
          "itinerary": false,
          "name": "List name",
          "pinpoints_order": [],
          "status": 3,
          "tags": ["some-tag", "another-tag"],
          "type": 0,
          "updated": "2023-12-31T08:52:37.330542Z",
          "user": 4567
      },
  // ... more lists
  ]
}

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)
  • Invalid tag format

Permissions​

The endpoint respects list visibility permissions:

  • Public lists: Visible to everyone
  • Shared lists: Visible if the livemap parameter is provided and if lists belong to that livemap
  • Private lists: Only visible to the list owner (authenticated users can see their own lists)

The permissions are automatically applied based on the authenticated user and on the livemap parameter if provided.

Query Parameters​

Text Search​

query (string, optional)​

Full-text search on the list's name, description, and address.

Searched Fields:

  • List name
  • List description
  • List address

Example:

GET /v3.0/lists/search?query=restaurants

Filtering by Collection​

These parameters allow you to filter lists by the collections or objects they are linked to: livemaps, pinpoints, portals, users. All of them are specified by their ID.

livemap (integer, optional)​

Filter lists belonging to a specific livemap.

Example:

GET /v3.0/lists/search?livemap=456

pinpoint (integer, optional)​

Filter lists that include a specific pinpoint in their collection. Since lists are collections of pinpoints, this returns all lists that contain the pinpoint with the specified ID.

Example:

GET /v3.0/lists/search?pinpoint=789

portal (integer, optional)​

Filter lists for a specific portal (searches all lists within livemaps belonging to that portal).

Example:

GET /v3.0/lists/search?portal=10

user (integer, optional)​

Filter lists created by a specific user.

Example:

GET /v3.0/lists/search?user=42

liked_by (integer, optional)​

Filter lists liked by a specific user, identified by its ID.

Example:

GET /v3.0/lists/search?liked_by=42

Attribute Filtering​

type (integer, optional)​

Filter lists by type. Values:

  • 0: General lists
  • 1: Featured lists

Example:

GET /v3.0/lists/search?type=1

itinerary (boolean, optional)​

Filter lists that are itineraries. If true, returns only itinerary lists. If false, returns only non-itinerary lists.

Example:

GET /v3.0/lists/search?itinerary=true

is_contributive (boolean, optional)​

Filter lists that are contributive. If true, returns only contributive lists. If false, returns only non-contributive lists.

Example:

GET /v3.0/lists/search?is_contributive=true

Tag Filtering​

tags (comma-separated string, optional)​

Filter lists that have the specified tags.

Use commas (,) to separate tag groups, which creates AND logic between groups. Within a tag group, use the pipe character (|) to create OR logic between tags.

Format:

  • Simple tags: tag1,tag2,tag3
  • Tag groups with OR: tag1|tag2,tag3 (means: (tag1 OR tag2) AND tag3)

Example:

GET /v3.0/lists/search?tags=restaurant,food
GET /v3.0/lists/search?tags=restaurant|bar,food

Sorting​

You can sort the results by relevance score (default sorting), by name, or by score and name combined.

Relevance sorting (default sorting)​

Results are ranked by relevance, which considers:

  • Recency: More recent lists (especially within the last 28 days) are ranked higher
  • Text match quality: Better matches to your search query are ranked higher

sort_by_name (string, optional)​

Sort results by list name. Values:

  • asc: Ascending order
  • desc: Descending order

Example:

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

sort_by_score_and_name (string, optional)​

Sort results by score and then by name. Values:

  • asc: Ascending order
  • desc: Descending order

Example:

GET /v3.0/lists/search?sort_by_score_and_name=desc

Pagination​

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