A newer version of this documentation is available.

View Latest

Run a Geospatial Search Query with the REST API and curl/HTTP

  • how-to
    +
    Search for geospatial data in your Couchbase Server database with a compatible Search index, the REST API and curl/HTTP.

    Prerequisites

    • You’ve deployed the Search Service on a node in your database.

    • You have a bucket with scopes and collections in your database.

    • Your user account has the Search Admin or Search Reader role.

    • You installed the Couchbase command-line tool (CLI).

    • You have the hostname or IP address for your database.

    Procedure

    To run a geospatial Search query, create a Search index with a geospatial type mapping.

    Create a Search Index with a Geospatial Type Mapping

    To create the Search index with a geospatial type mapping:

    1. Create a Search Index with the REST API and curl/HTTP with the following JSON payload, replacing all placeholder values that start with a $:

      {
          "type": "fulltext-index",
          "name": "$INDEX_NAME",
          "sourceType": "gocbcore",
          "sourceName": "$BUCKET_NAME",
          "planParams": {
            "maxPartitionsPerPIndex": 1024,
            "indexPartitions": 1
          },
          "params": {
            "doc_config": {
              "docid_prefix_delim": "",
              "docid_regexp": "",
              "mode": "scope.collection.type_field",
              "type_field": "type"
            },
            "mapping": {
              "analysis": {},
              "default_analyzer": "standard",
              "default_datetime_parser": "dateTimeOptional",
              "default_field": "_all",
              "default_mapping": {
                "dynamic": true,
                "enabled": false
              },
              "default_type": "_default",
              "docvalues_dynamic": false,
              "index_dynamic": true,
              "store_dynamic": false,
              "type_field": "_type",
              "types": {
                "$SCOPE_NAME.$COLLECTION_NAME": {
                  "dynamic": true,
                  "enabled": true,
                  "properties": {
                    "$FIELD_NAME": {
                      "dynamic": false,
                      "enabled": true,
                      "fields": [
                        {
                          "include_in_all": true,
                          "index": true,
                          "name": "$FIELD_NAME",
                          "type": "geopoint"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "store": {
              "indexType": "scorch",
              "segmentVersion": 15,
              "spatialPlugin": "s2"
            }
          },
          "sourceParams": {}
        }

    Run a Geospatial Search Query

    To run a Search query against the Search index:

    1. In your command-line tool, enter a curl command with the XPOST verb.

    2. Set your header content to include Content-Type: application/json.

    3. Enter your username, password, and the Search Service endpoint on port 8094 with the name of the index you want to query:

      curl -s -XPUT -H "Content-Type: application/json" \
      -u $CB_USERNAME:$CB_PASSWORD http://$CB_HOSTNAME:8094/api/index/$INDEX-NAME/query -d \
    4. Enter the JSON payload for your query.

      For example, the following query searches a geospatial field, geo, for any locations within a 100 mile radius of the coordinates -2.235143, 53.482358:

      {
          "from": 0,
          "size": 10,
          "query": {
            "location": {
              "lon": -2.235143,
              "lat": 53.482358
             },
              "distance": "100mi",
              "field": "geo"
            },
          "sort": [
            {
              "by": "geo_distance",
              "field": "geo",
              "unit": "mi",
              "location": {
              "lon": -2.235143,
              "lat": 53.482358
              }
            }
          ]
        }

    Next Steps

    You can customize your Search index to improve search results and performance.

    You can also:

    If you want to add autocomplete to your database’s search, see Use Autocomplete with the Search Service.