Skip to main content

Pinpoint Search

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

Overview​

The Pinpoints search endpoint provides a search interface for querying pinpoints (points of interest).

It supports the following types of filtering:

  • Text search: Full-text search on pinpoint names, descriptions, addresses, and tags
  • Collection filtering: Filter by lists, livemaps, portals, or users
  • Tag filtering: Filter by tags with support for AND/OR logic
  • Geographic filtering: Filter by location (bounding box coordinates, distance from points, and altitude ranges)
  • Geometry filtering: Filter by the type of geometric shape (Polygon, LineString) linked to the pinpoint
  • Ownership filtering: Filter pinpoints based on your relationship to them (pinpoints you've bookmarked, pinpoints owned by your friends, or pinpoints you own)
  • Other attribute filtering: Filter by country, level, and phone number

Endpoint: GET /v3.0/pinpoints/search

Response Format​

Success Response​

Status Code: 200 OK

Response Structure:

{
  "count": 123,
  "next": "https://api.getwemap.com/v3.0/pinpoints/search?limit=20&offset=40&query=museum",
  "previous": "https://api.getwemap.com/v3.0/pinpoints/search?limit=20&query=museum",
  "results": [
    {
        "altitude": 212.0,
        "country": "FR",
        "timezone": "Europe/Paris",
        "latitude": 48.20264816,
        "description": "Pinpoint description",
        "geo_entity_shape": null,
        "media_thumbnail_url": null,
        "type": 2,
        "media_url": "https://api.getwemap.com/images/pps-picpoints/cf7eYUYd43582c929fd24f99.55747949.png",
        "location_shape": null,
        "media_type": "image",
        "link_url": null,
        "id": 1234567890,
        "state": 1,
        "search_priority": 100,
        "media_credits": "Some provider name",
        "twitter_url": null,
        "longitude": 16.3591423,
        "facebook_url": null,
        "address": "Some address",
        "external_data": {
            "key": "value",
            "key2": "value2",
        },
        "extra_media_urls": ["https://api.getwemap.com/images/pps-picpoints/cf7eYUYgg3581c929fd24f99.55747949.png"],
        "like_count": 0,
        "level": 1.0,
        "author": {
            "name": "Author name",
            "photo_url": "https://api.getwemap.com/images/users/author-profile-photo.jpg"
        },
        "created": "2024-05-16T12:52:32.253132Z",
        "image_url": "https://api.getwemap.com/images/pps-categories/users/52b4b5e01005a0ca8690a84.36103366.png",
        "tags": [
            "some-tag",
            "another-tag",
        ],
        "phone": null,
        "name": "Pinpoint name",
        "opening_hours": null,
        "category": 456,
        "updated": "2023-12-11T14:06:05.186558Z",
        "user": 4567,
        "status": 3
    },
      // ... more pinpoints
  ]
}

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 date format
  • Invalid bounding box parameters
  • Invalid tag format
  • Invalid distance format
  • Invalid owns parameter values

Permissions​

The endpoint respects pinpoint visibility permissions:

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

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 pinpoint's fields. By default, searches in name, description, address, and tags. You can specify which fields to search using the query_fields parameter.

Example:

GET /v3.0/pinpoints/search?query=Louvre

Default Searched Fields (when query_fields is not specified):

  • Pinpoint name
  • Pinpoint description
  • Pinpoint address
  • Pinpoint tags

query_fields (comma-separated string, optional)​

A comma-separated list of fields to search in. If not specified, searches in name, description, address, and tags.

Example:

GET /v3.0/pinpoints/search?query=Paris&query_fields=name,address

query_mode (string, optional)​

Controls how the query is interpreted:

  • regular (default): Standard search with AND operator between terms
  • phrase: Phrase matching mode for exact phrase searches

Examples:

Regular mode (default):

GET /v3.0/pinpoints/search?query=art museum
GET /v3.0/pinpoints/search?query=art museum&query_mode=regular

This will find pinpoints that contain both "art" AND "museum" anywhere in the searched fields.

Phrase mode:

GET /v3.0/pinpoints/search?query=art museum&query_mode=phrase

This will find pinpoints that contain the exact phrase "art museum" in the specified fields.

Filtering by Collection​

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

list (integer, optional)​

Filter pinpoints belonging to a specific list.

Example:

GET /v3.0/pinpoints/search?list=123

livemap (integer, optional)​

Filter pinpoints from all lists that belong to a specific livemap.

Example:

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

portal (integer, optional)​

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

Example:

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

user (integer, optional)​

Filter pinpoints created by a specific user.

Example:

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

Ownership Filtering​

owns (comma-separated string, optional)​

Filter pinpoints based on ownership relationships. Accepts a comma-separated combination of:

  • bookmarked: Pinpoints bookmarked by the authenticated user
  • friends: Pinpoints owned by the authenticated user's friends
  • me: Pinpoints owned by the authenticated user

Note: This parameter requires authentication. If the user is not authenticated, this filter is ignored.

Example:

GET /v3.0/pinpoints/search?owns=bookmarked,me

liked_by (integer, optional)​

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

Example:

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

Tag Filtering​

tags (comma-separated string, optional)​

Filter pinpoints 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/pinpoints/search?tags=museum,art
GET /v3.0/pinpoints/search?tags=restaurant|bar,food

tags__overlap (comma-separated string, optional)​

Filter pinpoints that have at least one of the specified tags. Note: | is not allowed in this parameter.

Example:

GET /v3.0/pinpoints/search?tags__overlap=museum,restaurant,hotel

Attribute Filtering​

country (string, optional)​

Filter pinpoints by country code ("FR", "US").

Example:

GET /v3.0/pinpoints/search?country=FR

level (decimal, optional)​

Filter pinpoints that belong to a specific level (e.g., floor level in a building).

Example:

GET /v3.0/pinpoints/search?level=0.0

levels (comma-separated decimal, optional)​

Filter pinpoints that belong to at least one of the specified levels.

Example:

GET /v3.0/pinpoints/search?levels=0.0,1.0

phone (string, optional)​

Filter pinpoints by phone number.

Validation Rules: The following rules apply:

  1. International format: If the phone number includes a country code (starts with + that must be expressed as %2B in the URL), it must be in valid E.164 format and a valid phone number according to that country's numbering plan.
  2. National format: If the phone number doesn't include a country code, you must provide the country parameter (ISO 3166-1 alpha-2 code, e.g., FR, GB, US) to help parse the number.
  3. Validity check: The number must pass the library's validity check, which verifies that the number matches the actual phone number format for the specified country (correct number of digits, valid area codes, etc.).

Examples:

# International format (with country code)
GET /v3.0/pinpoints/search?phone=+79281230055
GET /v3.0/pinpoints/search?phone=+442077291888

# National format (requires country parameter)
GET /v3.0/pinpoints/search?phone=89281230055&country=RU
GET /v3.0/pinpoints/search?phone=2077291888&country=GB

Note: The phone number is normalized to E.164 format internally (e.g., +79281230055), so the search will match pinpoints stored in that format regardless of how the number was originally provided.

Geographic Filtering​

You can filter pinpoints based on their geographic location using bounding box coordinates, distance from points, and altitude ranges.

center_latitude (float, optional)​

Latitude of the bounding box center. Must be used together with center_longitude, latitude_delta, and longitude_delta.

Example:

GET /v3.0/pinpoints/search?center_latitude=48.8566&center_longitude=2.3522&latitude_delta=0.1&longitude_delta=0.1

center_longitude (float, optional)​

Longitude of the bounding box center. Must be used together with center_latitude, latitude_delta, and longitude_delta.

latitude_delta (float, optional)​

Height of the bounding box in degrees. Must be positive and ≤ 90. Required when using bounding box filtering.

longitude_delta (float, optional)​

Width of the bounding box in degrees. Must be positive and ≤ 180. Required when using bounding box filtering.

Note: All four parameters (center_latitude, center_longitude, latitude_delta, longitude_delta) must be provided together to enable bounding box filtering.

sort_by_distance_from (semicolon-separated string, optional)​

A semicolon-separated list of points in the format lon,lat or lon,lat;lon,lat for multiple points. Used together with distance to filter pinpoints. For multiple points, the distance is measured as the distance to the closest point on the line connecting the points.

Example:

GET /v3.0/pinpoints/search?sort_by_distance_from=2.3376,48.8606&distance=1km
GET /v3.0/pinpoints/search?sort_by_distance_from=2.3376,48.8606;2.3522,48.8566&distance=500m

distance (string, optional)​

Distance from the points specified in sort_by_distance_from. Format: a number followed by km or m (e.g., 1km, 500m). Must be used together with sort_by_distance_from.

Example:

GET /v3.0/pinpoints/search?sort_by_distance_from=2.3376,48.8606&distance=1km

minaltitude (float, optional)​

Minimum altitude in meters (inclusive). Must be used together with maxaltitude.

Example:

GET /v3.0/pinpoints/search?minaltitude=0&maxaltitude=1000

maxaltitude (float, optional)​

Maximum altitude in meters (exclusive). Must be used together with minaltitude.

Geometry Filtering​

You can filter pinpoints based on the type of geometric shape linked to them. This is different from geographic filtering, which filters by location coordinates.

geo_entity_shape_geometry_types (comma-separated string, optional)​

Filter pinpoints by the geometry type of the shape eventually linked to them. Accepts only one of the following values: Polygon, LineString.

Example:

GET /v3.0/pinpoints/search?geo_entity_shape_geometry_types=Polygon

remove_geo_entity_pinpoints (boolean, optional)​

If true, excludes pinpoints that have a geometric shape.

Example:

GET /v3.0/pinpoints/search?remove_geo_entity_pinpoints=true

Date Filtering​

updated__gte (ISO 8601 datetime, optional)​

Filter pinpoints updated on or after this date. Accepts ISO 8601 date and datetime formats.

Valid formats:

  • Date only: 2024-01-01 (time defaults to 00:00:00)
  • Full datetime with UTC: 2024-01-01T00:00:00Z or 2024-01-01T00:00:00.000Z

Examples:

GET /v3.0/pinpoints/search?updated__gte=2024-06-01
GET /v3.0/pinpoints/search?updated__gte=2024-06-01T00:00:00Z
GET /v3.0/pinpoints/search?updated__gte=2024-06-01T15:54:00.000Z

Sorting​

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

Relevance sorting (default sorting)​

Results are ranked by relevance, which considers:

  • Recency: More recent pinpoints (especially within the last 28 days) are ranked higher
  • Search priority: Pinpoints with higher search_priority values (between 1 and 100) appear first in search results
  • Text match quality: Better matches to your search query are ranked higher

sort_by_name (string, optional)​

Sort results by pinpoint name. Values:

  • asc: Ascending order
  • desc: Descending order

Example:

GET /v3.0/pinpoints/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/pinpoints/search?sort_by_score_and_name=desc

Note: When sort_by_distance_from and distance are provided, results are automatically sorted by distance from the specified points.

random (boolean, optional)​

If true, returns results in random order.

Example:

GET /v3.0/pinpoints/search?random=true

Pagination​

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

Output Format​

output_format (string, optional)​

Payload return format is default to json, reflecting wemap's data structure, but you can also get results in GeoJSON format by setting the output_format parameter to geojson.

as_mvt (boolean, optional)​

When output_format=geojson, this parameter formats the GeoJSON output for Mapbox Vector Tiles (MVT) compatibility. Default: false.

GeoJSON Response Structure:

{
    "type": "FeatureCollection",
    "count": 25,
    "next": "https://api.getwemap.com/v3.0/pinpoints/search?limit=20&offset=20&output_format=geojson",
    "previous": null,
    "features": [
        {
            "type": "Feature",
            "properties": {
                "address": "rue de Rivoli, 75001 Paris, France",
                "altitude": 35.0,
                "author": {
                    "name": "wemap_user",
                    "photo_url": "https://api.getwemap.com/images/users/25c87ff3066571fa4f695a3f.20878471.png"
                },
                "category": 1,
                "country": "FR",
                "created": "2025-06-11T14:08:18.984176Z",
                "description": "The world's largest art museum and a historic monument...",
                "external_data": null,
                "extra_media_urls": [],
                "facebook_url": null,
                "geo_entity_shape": null,
                "id": 1234567890,
                "image_url": "https://api.getwemap.com/images/pps-categories/icon_circle_maaap.png",
                "level": null,
                "like_count": 0,
                "link_url": null,
                "media_credits": "",
                "media_thumbnail_url": null,
                "media_type": null,
                "media_url": null,
                "name": "Mama Restaurant Paris West",
                "opening_hours": null,
                "phone": null,
                "state": 1,
                "status": 3,
                "search_priority": 100,
                "tags": [
                    "one_tag",
                    "two_tag",
                ],
                "timezone": null,
                "twitter_url": null,
                "type": 1,
                "updated": "2025-12-29T15:55:09.270834Z",
                "user": 34807,
                "location_shape": null,
                "max_level": null,
                "min_level": null
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    2.292081966201,
                    48.829078990421
                ]
            }
        },
        // ... more features
    ]
}