Getting Started

Introduction

Mosaix is a cloud-based Semantic Search as a Service platform for developers to build natural language understanding into their products.

By using Mosaix's Deep Semantic Search engine, this API service enables developers to retrieve the interpretations of user's natural language input and also fulfillments for direct actions on the client side.

Mosaix can be integrated with mobile applications, cloud software, bots, and speech-enabled IoT devices like TV, speakers, headphones, connected cars and more.

How it works?

Image of Mosaix Flow

The base address of the API is https://api.mosaix.ai.

Authorization

Sign Up

 curl -d '{
        "email": `${yourEmail}`
      }'
      -H "Content-Type: application/json"
      -X POST "https://api.mosaix.ai/v1/signup"

You should receive an email verification from us. Click attached link in the email, it will direct you to the log in screen where you can find your clientId and clientSecret in the settings. Save them somewhere safe.

Get Token

 curl -d '{
        "clientSecret": `${yourClientSecret}`,
        "clientId": `${yourClientId}`
      }'
      -H "Content-Type: application/json"
      -X POST "https://api.mosaix.ai/v1/createtoken"

Request

The request is based on REST principles, where data sources are accessed via standard https request in UTF-8 format to an API endpoint. As for now, the API supports POST request only.

Sample curl request

 curl -d '{"query": "play coldplay", "latitude": 37.424107, "longitude": -122.16607, "spotifyToken":`#{user's spotify token}`}, "nprToken":`#{user's npr token}`'
      -H "Content-Type: application/json"
      -H "Authorization: Bearer {your api access token}"
      -H "Device-Id": `${your device's id}`
      -H "Region-Code": `${your ISO 3166-1 alpha-2 code}`
      -H "Language-Code": `${your ISO 639-1 code}`
      -H "Id": `${End-User-Id}`
      -X POST "https://api.mosaix.ai/v1/texttofulfillment"

Descriptions

Header Field

Authorization (*)

 This is the api access token assigned to each thrid party clients.
 You will need to provide an email to retrieve the access token.

Device-Id (*)

 `Device-Id` is an unique id from terminal such as phone / pc / smart speaker / smart TV / connected cars / IoT.

Id (*)

 This is a unique user id generated by Mosaix's API server. To get this unique user id,
 client should send a POST request with end user's email to `/v1/endUser`.

For more details, please visit get end user id

Region-Code (*)

ISO 3166-1 alpha-2 code: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

Language-Code (*)

ISO 639-1 code: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

Data Field

query (*)

 User's input in text string.

spotifyToken (*?)

 User's spotify access token.

nprToken (*?)

 User's npr access token.

latitude (*?)

 Latitude and longitude fields are required if client enabled navigation domains during
 creating the client ID. Once enabled, these two fields should be added in the the POST body
 of each request.

 The latitude of the user's current position based on the client's best knowledge.
 This field must be omitted if the client doesn't have a way to know its position.

 Range:    -90 <= #{value} <= 90

 This field is assumed to be in the WGS84 coordinate system.

longitude (*?)

 The longitude of the user's current position based on the client's best knowledge.
 This field must be omitted if the client doesn't have a way to know its position.

 Range:    -180 <= #{value} <= 180

 This field is assumed to be in the WGS84 coordinate system.

(*) required field for each query

(*?) required for specific types of queries where more personalized results will be generated

Response

The mosaix NLU engine reatuns a JSON object to each https POST request.

Sample response

{
    "version": "0.0.1",
    "mode": "none",
    "utterance": "How is the traffic to Saymosaic in Palo Alto",
    "session": {},
    "id": "76850e6a-88f2-4ab8-8f4a-61107aa2cb85",
    "interpretations": [
        {
            "domain": "navigation",
            "intent": "traffic",
            "score": 3.206740617752075,
            "speechText": "The traffic congestion level is light",
            "displayText": "Traffic to  saymosaic",
            "debug": {},
            "hints": [],
            "fulfillment": {
                "destination": "saymosaic",
                "command": "search",
                "option": "summary",
                "thirdPartyResults": [
                    {
                        "source": "Google",
                        "area": {
                            "address": "Palo Alto, CA, USA",
                            "name": "Palo Alto",
                            "placeId": "ChIJORy6nXuwj4ARz3b1NVL1Hw4",
                            "longitude": -122.1430195,
                            "latitude": 37.4418834
                        },
                        "origin": {
                            "address": "",
                            "name": "Current location",
                            "placeId": "",
                            "longitude": -122.166077,
                            "latitude": 37.424107
                        },
                        "destinations": [
                            {
                                "placeId": "ChIJBzAxdz66j4ARuEJguweiVCo",
                                "address": "",
                                "longitude": -122.1011113,
                                "latitude": 37.4310403,
                                "name": "SayMosaic",
                                "basicInfo": {
                                    "openNow": true,
                                    "vicinity": "1121 San Antonio Rd Suite B100, Palo Alto",
                                    "rating": 4.5,
                                    "icon": "http://localhost:3000/v1/pick?link=aHR0cHM6Ly9tYXBzLmdzdGF0aWMuY29tL21hcGZpbGVzL3BsYWNlX2FwaS9pY29ucy9nZW5lcmljX2J1c2luZXNzLTcxLnBuZw==&id=502dd33f-98af-4184-8b3a-6cfe17e488ca&rid=13977f21-0e9d-4b37-aa7c-b3bee081694e",
                                    "photosLink": "http://localhost:3000/v1/pick?link=aHR0cHM6Ly9tYXBzLmdvb2dsZS5jb20vbWFwcy9jb250cmliLzExMzEzODQzNTQ3MDk1MTI3MDc3Ny9waG90b3M=&id=502dd33f-98af-4184-8b3a-6cfe17e488ca&rid=13977f21-0e9d-4b37-aa7c-b3bee081694e"
                                },
                                "id": "94dfce90-97e8-4ff8-8536-53a28840a728",
                                "trafficInfo": {
                                    "distanceText": "6.0 mi",
                                    "distanceValue": 9735,
                                    "durationText": "18 mins",
                                    "durationValue": 1066,
                                    "durationInTrafficText": "17 mins",
                                    "durationInTrafficValue": 1049,
                                    "summary": "Embarcadero Rd and E Bayshore Rd",
                                    "congestionLevel": "light"
                                }
                            }
                        ]
                    }
                ]
            }
        }
    ]
}