IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« External Identities API Reference OAuth Service API Reference »

› ›

Search API Reference

edit

Search API Reference

edit

The Custom search experiences guide provides a conceptual walkthrough of the steps involved in issuing search requests on behalf of users via OAuth.

In this API reference

edit

Search API Overview

edit

POST http://localhost:3002/api/ws/v1/search

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`query`	optional	The search query
`page`	optional	Provides optional keys of size and current. Specifies the number of results per page and which page the API should return.
`sort`	optional	Sort results ASC or DESC for a field
`search_fields`	optional	Fields used for full-text matching
`result_fields`	optional	Fields returned in the JSON response
`filters`	optional	Query modifiers used to refine a query
`facets`	optional	Faceting configuration

Search Query

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`query`	optional	A string or number used to find related documents

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali"
}'

Pagination

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`page`	optional	Provides optional keys of size and current. Specifies the number of results per page and which page the API should return.
`size`	optional	Specifies the number of results per page
`current`	optional	Specifies which page of results to retrieve for the query

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali",
  "page": {
    "size": 1,
    "current": 1
  }
}'

Sorting

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`sort`	optional	Sort results ASC or DESC for one or multiple field
`field`	field	Name of the field used for sorting
`value`	direction	ASC or DESC direction for sorting

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali",
  "sort": [
    { "square_km": "desc" },
    { "date_established": "asc" }
  ]
}'

Search Fields

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`search_fields`	optional	Fields used for full-text matching
`field`	field	Name of the field used for full-text matching
`weight`	integer	The relative importance of fields in a query. A higher value represents greater importance for algorithmic scoring.

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali",
  "search_fields": {
    "title": {
      "weight": 10
    },
    "description": {}
  }
}'

Result Fields

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`result_fields`	optional	Fields returned in the JSON response
`field`	field	Children of the `result_fields` object. Name of the field to be returned in the response
`raw`	result type	Value of the field as originally indexed
`snippet`	result type	Value of the field with highlighting markup added to visually distinguish where the match occurred
`size`	integer	Character length of the returned value
`fallback`	boolean	For `snippet` only. Returns the `raw` value as `snippet` even when no match was highlighted

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "query": "america",
  "result_fields": {
    "title": {
      "raw": {},
      "snippet": {}
    },
    "description": {
      "raw": {
        "size": 50
      },
      "snippet": {
        "fallback": true,
        "size": 50
      }
    },
    "states": {
      "snippet": {
        "size": 50
      }
    }
  }
}'

{
  "meta": {
    ...
  },
  "results": [
    {
      "title": {
        "raw": "American Samoa",
        "snippet": "<em>American</em> Samoa"
      },
      "_meta": {
        "source": "custom",
        "last_updated": "2020-03-27T20:10:33+00:00",
        "content_source_id": "5e7e5d911897c6dbb7e3e72a",
        "id": "park_american-samoa",
        "score": 6.359234
      },
      "source": {
        "raw": "custom"
      },
      "states": {
        "snippet": "<em>American</em> Samoa"
      },
      "description": {
        "raw": "The southernmost National Park is on three Samoan",
        "snippet": "The southernmost National Park is on three Samoan"
      },
      "last_updated": {
        "raw": "2020-03-27T20:10:33+00:00"
      },
      "content_source_id": {
        "raw": "5e7e5d911897c6dbb7e3e72a"
      },
      "id": {
        "raw": "park_american-samoa"
      }
    },
    {
      "title": {
        "raw": "Denali",
        "snippet": null
      },
      "_meta": {
        "source": "custom",
        "last_updated": "2020-03-27T20:10:33+00:00",
        "content_source_id": "5e7e5d911897c6dbb7e3e72a",
        "id": "park_denali",
        "score": 6.357545
      },
      "source": {
        "raw": "custom"
      },
      "states": {
        "snippet": null
      },
      "description": {
        "raw": "Centered on Denali, the tallest mountain in North",
        "snippet": " <em>America</em>, Denali is serviced by a single road"
      },
      "last_updated": {
        "raw": "2020-03-27T20:10:33+00:00"
      },
      "content_source_id": {
        "raw": "5e7e5d911897c6dbb7e3e72a"
      },
      "id": {
        "raw": "park_denali"
      }
    },
    ...
  ]
}

Value Filters

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`filters`	optional	Query modifiers used to refine a query
`field`	field	Name of field upon which to apply your filter
`field value`	field value	The value upon which to filter. The value must be an exact match, even casing: `True` will not match on `true`.

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "filters": {
    "states": ["California", "Washington"]
  }
}'

Range Filters

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`filters`	optional	Query modifiers used to refine a query
`field`	field	Name of field upon which to apply your filter
`from`	optional	Inclusive lower bound of the range. Is required if `to` is not provided.
`to`	optional	Exclusive upper bound of the range. Is required if `from` is not provided.

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "filters": {
    "visitors": {
      "from": 100
    },
    {
      "date_established": {
        "to": "1900-01-01"
      }
    }
  }
}'

Geo Filters

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`filters`	optional	Query modifiers used to refine a query
`field`	field	Name of field upon which to apply your filter
`center`	required	The mode of the distribution as a string in "[latitude], [longitude]" format.
`unit`	required	The base unit of measurement: `mm`, `cm`, `m` (meters), `km`, `in`, `ft`, `yd`, or `mi` (miles).
`distance`	optional	A number representing the distance unit. Is required if `from` or `to` is not given.
`from`	optional	Inclusive lower bound of the range. Is required if `to` is not provided.
`to`	optional	Exclusive upper bound of the range. Is required if `from` is not provided.

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "filters": {
    "location": {
      "unit": "km",
      "center": "47.6062,122.3321",
      "distance": 1000
    }
  }
}'

Combining Filters

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`filters`	optional	Query modifiers used to refine a query
`all`	array	At least one of the filters must match. This functions as an `OR` condition.
`any`	array	All of the filters must match. This functions as an `AND` condition.
`none`	array	All of the filters must not match. This functions as a `NOT` condition.

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "filters": {
    "all": [
      {
        "states": ["California", "Washington"]
      },
      {
        "visitors": {
          "from": 100
        }
      },
      {
        "date_established": {
          "to": "1900-01-01"
        }
      }
    ],
    "any": [
      {
        "location": {
          "unit": "km",
          "center": "47.6062,122.3321",
          "distance": 1000
        }
      },
      {
        "location": {
          "unit": "km",
          "center": "37.7749,122.4194",
          "from": 100,
          "to": 10000
        }
      }
    ],
    "none": {
      "world_heritage_site": "true"
    }
  }
}'

Value Facets

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`facets`	optional	Faceting configuration
`field`	field	Name of field upon which to apply your facet
`type`	required	Type of facet, in this case `value`
`name`	optional	Name given to facet
`size`	optional	Between 1 and 250, defaults to 10
`sort`	optional	JSON object where the key is either `count` or `value` and the value is `asc` or `desc`. The default is sorting by descending count.

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "facets": {
    "states": {
      "type": "value",
      "name": "top-five-states",
      "sort": { "count": "desc" },
      "size": 5
    }
  }
}'

{
  "meta": {
    ...
  },
  "results": [
    ...
  ],
  "facets": {
    "states": [
      {
        "type": "value",
        "data": [
          {
            "value": "Alaska",
            "count": 5
          },
          {
            "value": "Utah",
            "count": 2
          },
          {
            "value": "Colorado",
            "count": 2
          },
          {
            "value": "California",
            "count": 2
          },
          {
            "value": "Washington",
            "count": 1
          }
        ],
        "name": "top-five-states"
      }
    ],
  }
}

Range Facets

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`facets`	optional	Faceting configuration
`field`	field	Name of field upon which to apply your facet
`type`	required	Type of facet, in this case `range`
`name`	optional	Name given to facet
`ranges`	optional	An array of range objects
`from`	optional	Inclusive lower bound of the range. Is required if `to` is not provided.
`to`	optional	Exclusive upper bound of the range. Is required if `from` is not provided.
`name`	optional	Name given to range

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "facets": {
    "acres": [
      {
        "type": "range",
        "name": "min-and-max-range",
        "ranges": [
          { "from": 1, "to": 10000 },
          { "from": 10000 }
        ]
      }
    ],
    "date_established": {
      "type": "range",
      "name": "half-century",
      "ranges": [
        { "from": "1900-01-01T12:00:00+00:00", "to": "1950-01-01T00:00:00+00:00" }
      ]
    }
  }
}'

{
  "meta": {
    ...
  },
  "results": [
    ...
  ],
  "facets": {
    "acres": [
      {
        "type": "range",
        "data": [
          {
            "key": "5e7e6cbd1897c6aa79a79c95",
            "from": 1,
            "to": 10000,
            "count": 1
          },
          {
            "key": "5e7e6cbd1897c6aa79a79c96",
            "from": 10000,
            "count": 19
          }
        ],
        "name": "min-and-max-range"
      }
    ],
    "date_established": [
      {
        "type": "range",
        "data": [
          {
            "key": "5e7e6cbd1897c6aa79a79c97",
            "from": "1900-01-01T12:00:00.000Z",
            "to": "1950-01-01T00:00:00.000Z",
            "count": 11
          }
        ],
        "name": "half-century"
      }
    ]
  }
}

Geolocation Facets

edit

`access_token`	required	Must be included in HTTP authorization headers, is acquired via an OAuth authorization flow.
`facets`	optional	Faceting configuration
`field`	field	Name of field upon which to apply your facet
`type`	required	Type of facet, in this case `range`
`name`	optional	Name given to facet
`ranges`	optional	An array of range objects
`from`	optional	Inclusive lower bound of the range. Is required if `to` is not provided.
`to`	optional	Exclusive upper bound of the range. Is required if `from` is not provided.
`center`	required	The mode of the distribution as a string in "[latitude], [longitude]" format.
`unit`	required	The base unit of measurement: `mm`, `cm`, `m` (meters), `km`, `in`, `ft`, `yd`, or `mi` (miles).
`name`	optional	Name given to range

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "facets": {
    "location": {
      "type": "range",
      "name": "geo-range-from-san-francisco",
      "center": "37.386483, -122.083842",
      "unit": "m",
      "ranges": [
        { "from": 0, "to": 100000, "name": "Nearby" },
        { "from": 100000, "to": 300000, "name": "A longer drive." },
        { "from": 300000, "name": "Perhaps fly?" }
      ]
    }
  }
}'

{
  "meta": {
    ...
  },
  "results": [
    ...
  ],
  "facets": {
    "location": [
      {
        "type": "range",
        "data": [
          {
            "key": "Nearby",
            "from": 0,
            "to": 100000,
            "count": 0
          },
          {
            "key": "A longer drive.",
            "from": 100000,
            "to": 300000,
            "count": 0
          },
          {
            "key": "Perhaps fly?",
            "from": 300000,
            "count": 20
          }
        ],
        "name": "geo-range-from-san-francisco"
      }
    ]
  }
}

« External Identities API Reference OAuth Service API Reference »