Streams: Get

Retrieve records by ID from a Streams Endpoint

path Parameters
accountId
required
string
endpoint
required
string

The ID of the Streams Endpoint to query.

ids
required
Array of strings

The Streams records to get. Multiple record IDs can be provided separated by commas.

query Parameters
v
required
string

A date in YYYYMMDD format.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Streams: List

List records from a Streams Endpoint

Streams API provides the ability for a user to filter and sort records by the contents of an indexed field. The filters and sorting parameters can be provided as query parameters, in addition to the query parameters documented here. If no filters are provided, the API returns all the records (with pagination).

For example, with the parameter name=Alice, only records where the field name has value Alice will be returned.

Similarly, adding the parameters name__in=Alice and name__in=Bob will result in records with name equal to Alice OR name equal to Bob being returned.

Filters

Filters are supported on Text, Numeric, Date and DateTime fields, although not all filters are supported by all fields. It is also possible to filter on an array of strings, or a string field nested in an array of objects. In this case, the record will be present in the response if one of the field values in the array matches the filter.

Multiple filters on different fields and different filter types can be combined in the same query. An indexed field with an object can be filtered by using the dot notation, for example, address.city=Brooklyn.

A number of different types of filters are supported.

Equals

This can be specified as simple query parameter.

Supported Types: Text, Numeric, Date, DateTime, Fields within Arrays.

Example: Adding &name=Alice as a query parameter will return records where the name field matches Alice.

Not Equals

This can be specified with the neq modifier to the query parameter key.

Supported Types: Text, Numeric, Date, DateTime, Fields within Arrays.

Example: Adding &name__neq=Alice as a query parameter will return records where the name field does not match Alice.

Equals Any Of

This is basically an OR clause for Equals on a given field. This can be specified with the in modifier to the query parameter key.

Supported Types: Text, Numeric, Date, DateTime, Fields within Arrays.

Example: Adding &name__in=Alice&name__in=Bob as a query parameter will return records where the name field matches either Alice or Bob.

Comparison

The following comparison filters are supported:

  • Greater Than with the modifier gt
  • Greater Than Or Equals with the modifier gte
  • Less Than with the modifier lt
  • Less Than Or Equals with the modifier lte

Supported Types: Numeric, Date, DateTime.

Example: Adding &createdDate__gt=2020-11-11&rating__gte=4 as a query parameter will return records where the createdDate is after 2020-11-11 and the rating field has a value greater than or equal to 4.

GeoSearch

Supports filtering to records for which the specified field is within the supplied radius to the supplied latitude and longitude.

Supported Types: Coordinates (ex: yextDisplayCoordinate, displayCoordinate, etc.).

GeoSearch queries are constructed by appending a __geo comparator to a coordinate field in the request. The details of the GeoSearch must then be included, comma separated, as part of the query value, optionally surrounded by parantheses.

The following parameters are supported:

  • The latitude of the point to geosearch from, specified as lat
  • The longitude of the point to geosearch from, specified as lon
  • The numeric radius from the point which results will be filtered to, specifed as radius
  • The unit of measurement for the radius, specified as unit. One of km, mi, m, ft. Defaults to mi

Example: Adding &yextDisplayCoordinate__geo=(lat:40.740,lon:-73.987565,radius:50,unit:km) as a query parameter will return records where the yextDisplayCoordinate field on the entities is within 50 km of the provided latitude and longitude.

Like all other filters, the field which is being geosearched upon must be specified in the fieldIndexes of the endpoint definition.

Sorting

Streams Endpoints support sorting by an indexed field. This can be enabled by adding the $sortBy query parameter with field name as the value. Optionally, the modifiers asc and desc can be added to indicate sorting by ascending and descending orders respectively. If no modifier is specified, the results will be returned in descending order.

Currently, sorting is only supported on a single field per request.

Example: Adding &$sortBy__desc=createdDate as a query parameter will return records with the most recent createdDate first.

Additional Notes on Supported Types

Indexes are supported on String, Numeric, Date and DateTime types. The set of supported filters for each type is documented in the previous section.

String

Streams Endpoints support indexing UTF-8 strings with a maximum length of 256 characters.

Date and DateTime

  • The timezone information on a DateTime, if present, will be stripped away during indexing, without converting the time to another timezone.
  • For indexing, the system expects to get RFC3339 DateTime format for DateTimes and YYYY-MM-DD for Dates.
  • For querying, API accepts the following formats: YYYY-MM-DD, YYYY-MM-DDTHH, YYYY-MM-DDTHH:MM and YYYY-MM-DDTHH:MM:SS.
path Parameters
accountId
required
string
endpoint
required
string

The ID of the Streams Endpoint to query.

query Parameters
v
required
string

A date in YYYYMMDD format.

limit
integer <= 50
Default: 10

Number of results to return.

pageToken
string

If a response to a previous request contained the nextPageToken field, pass that field's value as the pageToken parameter to retrieve the next page of data.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}