Segment Search endpoint
Segment Search is used to search fields contained across various data sources and return them in near real-time.
This guide provides information to help you better understand Segment Search and includes sample API calls for performing basic actions using the API.
Getting started
The endpoints used in this guide are part of the Adobe Experience Platform Segmentation Service API. Before continuing, please review the getting started guide for important information that you need to know in order to successfully make calls to the API, including required headers and how to read example API calls.
In addition to the required headers outlined in the getting started section, all requests to the Segment Search endpoint require the following additional header:
- x-ups-search-version: “1.0”
Search across multiple namespaces
This search endpoint can be used to search across various namespaces, returning a list of search count results. Multiple parameters can be used, separated by ampersands (&).
API format
GET /search/namespaces?schema.name={SCHEMA}
GET /search/namespaces?schema.name={SCHEMA}&s={SEARCH_TERM}
schema.name={SCHEMA}
_xdm.context.segmentdefinition
is supported.s={SEARCH_TERM}
schema.name
will be returned. A more detailed explanation can be found in the appendix of this document.Request
curl -X GET \
https://platform.adobe.io/data/core/ups/search/namespaces?schema.name=_xdm.context.segmentdefinition \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'x-ups-search-version: 1.0'
Response
A successful response returns HTTP status 200 with the following information.
{
"namespaces": [
{
"namespace": "AAMTraits",
"displayName": "AAMTraits",
"count": 45
},
{
"namespace": "AAMSegments",
"displayName": "AAMSegment",
"count": 10
},
{
"namespace": "SegmentsAISegments",
"displayName": "SegmentSAISegment",
"count": 3
}
],
"totalCount": 3,
"status": {
"message": "Success"
}
}
Search individual entities
This search endpoint can be used to retrieve a list of all full text indexed objects within the specified namespace. Multiple parameters can be used, separated by ampersands (&).
API format
GET /search/entities?schema.name={SCHEMA}&namespace={NAMESPACE}
GET /search/entities?schema.name={SCHEMA}&namespace={NAMESPACE}&s={SEARCH_TERM}
GET /search/entities?schema.name={SCHEMA}&namespace={NAMESPACE}&entityId={ENTITY_ID}
schema.name={SCHEMA}
_xdm.context.segmentdefinition
is supported.namespace={NAMESPACE}
s={SEARCH_TERM}
schema.name
will be returned. A more detailed explanation can be found in the appendix of this document.entityId={ENTITY_ID}
limit={LIMIT}
page={PAGE}
Request
curl -X GET \
https://platform.adobe.io/data/core/ups/search/entities?schema.name=_xdm.context.segmentdefinition&namespace=AAMSegments \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'x-ups-search-version: 1.0'
Response
A successful response returns HTTP status 200 with results matching the search query.
{
"entities": [
{
"id": "1012667",
"base64EncodedSourceId": "RFVGamdydHpEdy01ZTE1ZGJlZGE4YjAxMzE4YWExZWY1MzM1",
"sourceId": "DUFjgrtzDw-5e15dbeda8b01318aa1ef533",
"isFolder": true,
"parentFolderId": "974139",
"name": "aam-47995 verification (100)"
},
{
"id": "14653311",
"base64EncodedSourceId": "REVGamduLVgzdy01ZTE2ZjRhNjc1ZDZhMDE4YThhZDM3NmY1",
"sourceId": "DEFjgn-X3w-5e16f4a675d6a018a8ad376f",
"isFolder": false,
"parentFolderId": "324050",
"name": "AAM - Heavy equipment",
"description": "AAM - Acme Equipment"
}
],
"page": {
"totalCount": 2,
"totalPages": 1,
"pageOffset": 0,
"pageSize": 10
},
"status": {
"message": "Success"
}
}
Get structural information about a search object
This search endpoint can be used to get the structural information about the requested search object.
API format
GET /search/taxonomy?schema.name={SCHEMA}&namespace={NAMESPACE}&entityId={ENTITY_ID}
schema.name={SCHEMA}
_xdm.context.segmentdefinition
is supported.namespace={NAMESPACE}
entityId={ENTITY_ID}
Request
curl -X GET \
https://platform.adobe.io/data/core/ups/search/taxonomy?schema.name=_xdm.context.segmentdefinition&namespace=AAMSegments&entityId=porsche11037 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'x-ups-search-version: 1.0'
Response
A successful response returns HTTP status 200 with detailed structural information about the requested search object.
{
"taxonomy": [
{
"id": "0",
"base64EncodedSourceId": "RFVGZ01BLTVlNjgzMGZjMzk3YjQ1MThhYWExYTA4Zg2",
"name": "AAMTraits for Cars",
"parentFolderId": "root"
},
{
"id": "150561",
"base64EncodedSourceId": "RFVGamdpRk1BZy01ZTY4MzBmYzM5N2I0NTE4YWFhMWEwOGY1",
"name": "Fast Cars",
"parentFolderId": "carTraits"
},
{
"id": "porsche11037",
"base64EncodedSourceId": "REFGZ01CLTVlNjczMGZjMzk3YjQ1MThhZGIxYTA4Zg==",
"name": "Porsche",
"parentFolderId": "redCarsFolderId"
}
],
"status": {
"message": "Success"
}
}
Next steps
After reading this guide you now have a better understanding of how Segment Search works.
Appendix appendix
The following sections provide additional information about how search terms work. Search queries are written in the following manner: s={FieldName}:{SearchExpression}
. So, for example, to search for a segment definition named AAM or Platform, you would use the following search query: s=segmentName:AAM%20OR%20Platform
.
![NOTE] For best practices, the search expression should be HTML encoded, like the example shown above.
Search fields search-fields
The following table lists the fields which can be searched within the search query parameter.
Search expression search-expression
The following table lists the specifics of how search queries works when using the Segment Search API.
![NOTE] The following examples are shown in a non-HTML encoded format for better clarity. For best practices, HTML encode your search expression.
"hotel airport"~5
will find the terms “hotel” and “airport” within 5 words of each other in a document./a[0-9]+b$/
/[mh]otel/
. Regular expression searches are matched against single words.For more detailed documentation about the query syntax, please read the Lucene query syntax documentation.