Dataspike logo
Dataspike logo

API How to

In this example we will show how to use Search API with combination of Watch API

Search API was designed to check existence of particular person in Sanctions and PEP Lists
Watch API provides monitoring functionality, to check updated of both existed and non-existed persons

Step 1

Let's search for Donald Trump

curl -X POST\
-H "ds-api-token: [[apiKey]]"\
-H "Accept: application/json"\
-H "Content-Type: application/json"\
https://api.dataspike.io/api/v2/sealed/universal/search

Parameters
Body parameters

{
 "name":"Donald Trump"
}

Response Example:

{
    "requested_name": "Donald Trump",
    "search_uuid": "df6e9e48-aad7-457a-987c-c504c7914ccb",
    "data": [
              {
            "uuid": "c998b276-5698-4611-b581-50c4b91465a2",
            "category": "person",
            "main_name": "Donald Trump",
            "lookup_name": "donald trump",
            "fields": {
                "Alias": {
                    "type": "StringField",
                    "title": "Alias",
                    "values": [
                        "Donald Trump"
                    ]
                },
                "Links": {
                    "type": "URLField",
                    "title": "Links",
                    "values": [
                        {
                            "name": "WikiData Org",
                            "url": "https://www.wikidata.org/wiki/Q22686"
                        }
                    ]
                },
                "Politician role": {
                    "type": "StringField",
                    "title": "Politician role",
                    "values": [
                        "President of the united states since 2017-01-20"
                    ]
                },
                "Primary birth location": {
                    "type": "StringField",
                    "title": "Primary birth location",
                    "values": [
                        "Jamaica Hospital"
                    ]
                },
                "Citizenship": {
                    "type": "StringField",
                    "title": "Citizenship",
                    "values": [
                        "United States of America"
                    ]
                },
                "Gender": {
                    "type": "StringField",
                    "title": "Gender",
                    "values": [
                        "Male"
                    ]
                },
                "Primary date of birth": {
                    "type": "StringField",
                    "title": "Primary date of birth",
                    "values": [
                        "14 Jun 1946"
                    ]
                },
                "Possible dates of birth": {
                    "type": "StringField",
                    "title": "Possible dates of birth",
                    "values": [
                        "14 Jun 1946"
                    ]
                },
                "Possible location of birth": {
                    "type": "StringField",
                    "title": "Possible location of birth",
                    "values": [
                        "Jamaica Hospital"
                    ]
                },
                "Related news": {
                    "type": "URLField",
                    "title": "Related news",
                    "values": [
                        ...
                    ]
                },
                "Summary": {
                    "type": "StringField",
                    "title": "Summary",
                    "values": [
                        "45th and current president of the United States"
                    ]
                }
            },
            "similarity": 1.0
        },
    ]
}

Step 2

In Step 1 we could have two possible outcomes

  1. We found desired person and it has uuid field (unique identifier): uuid: c998b276-5698-4611-b581-50c4b91465a2
  2. We did not find person

And now we want to start monitoring the updates of existing person or new appearance of non-existing

Let's create Watch List for our monitoring purpose and keep it id:

curl -X POST\
-H "ds-api-token: [[apiKey]]"\
-H "Accept: application/json"\
-H "Content-Type: application/json"\
https://api.dataspike.io/api/v2/sealed/watch/lists/create

Parameters
Body parameters

{
 "name":"Donald Trump lists"
}

Response Example:

{
    "id":"032f6b0a-1ce1-44ea-a67b-cec9f6b37c55"
}

Now we are able to add person from Step 1 to our new Watch List with id:032f6b0a-1ce1-44ea-a67b-cec9f6b37c55

In case person was found we will use uuid: c998b276-5698-4611-b581-50c4b91465a2

curl -X POST\
-H "ds-api-token: [[apiKey]]"\
-H "Content-Type: application/json"\
https://api.dataspike.io/api/v2/sealed/watch/list/032f6b0a-1ce1-44ea-a67b-cec9f6b37c55/add

Parameters
Path parameters, id of created watch list

    "id" : "032f6b0a-1ce1-44ea-a67b-cec9f6b37c55"

In case person was found we will use uuid: c998b276-5698-4611-b581-50c4b91465a2
Body parameters

{
    "uuid": "c998b276-5698-4611-b581-50c4b91465a2"
}

In case person was NOT found we do not have uuid yet, so we just add the actual name

{
   "name": "Donald Trump"
}

Step 3

From now on we just need to check the status of our watch list for new updates:

curl -X GET\
-H "ds-api-token: [[apiKey]]"\
-H "Accept: application/json"\
https://api.dataspike.io/api/v2/sealed/watch/list/032f6b0a-1ce1-44ea-a67b-cec9f6b37c55/info

Parameters
Path parameters

    "id" : "032f6b0a-1ce1-44ea-a67b-cec9f6b37c55"

Response Example:

{
    "id": "032f6b0a-1ce1-44ea-a67b-cec9f6b37c55",
    "user_id": 1,
    "name": "Donald Trump lists",
    "last_viewed": "2021-02-02T13:54:26.708212Z",
    "created_at": "2021-02-02T13:54:26.708212Z",
    "updated_at": "2021-02-02T13:54:26.708212Z",
    "count": 2
}

If updated_at by system is greater than last_viewed, than new information for some person were added and you are able to check the changes

curl -X GET\
-H "ds-api-token: [[apiKey]]"\
-H "Accept: application/json"\
https://api.dataspike.io/api/v2/sealed/watch/list/032f6b0a-1ce1-44ea-a67b-cec9f6b37c55

Parameters
Path parameters

    "id" : "032f6b0a-1ce1-44ea-a67b-cec9f6b37c55"

Response Example:

{
   "data": [
             {
            "row_id": 329,
            "id": "032f6b0a-1ce1-44ea-a67b-cec9f6b37c55",
            "uuid": "c998b276-5698-4611-b581-50c4b91465a2",
            "status": 1,
            "item": {
                "uuid": "c998b276-5698-4611-b581-50c4b91465a2",
                "category": "person",
                "main_name": "Donald Trump",
                "lookup_name": "Donald Trump",
                "fields": {
                    "Alias": {
                        "type": "StringField",
                        "title": "Alias",
                        "values": [
                            "Donald Trump"
                        ]
                    },
                    "Links": {
                        "type": "URLField",
                        "title": "Links",
                        "values": [
                            {
                                "name": "WikiData Org",
                                "url": "https://www.wikidata.org/wiki/Q22686"
                            }
                        ]
                    },
                    "Politician role": {
                        "type": "StringField",
                        "title": "Politician role",
                        "values": [
                            "President of the united states since 2017-01-20"
                        ]
                    },
                    "Primary birth location": {
                        "type": "StringField",
                        "title": "Primary birth location",
                        "values": [
                            "Jamaica Hospital"
                        ]
                    },
                    "Citizenship": {
                        "type": "StringField",
                        "title": "Citizenship",
                        "values": [
                            "United States of America"
                        ]
                    },
                    "Gender": {
                        "type": "StringField",
                        "title": "Gender",
                        "values": [
                            "Male"
                        ]
                    },
                    "Primary date of birth": {
                        "type": "StringField",
                        "title": "Primary date of birth",
                        "values": [
                            "14 Jun 1946"
                        ]
                    },
                    "Possible dates of birth": {
                        "type": "StringField",
                        "title": "Possible dates of birth",
                        "values": [
                            "14 Jun 1946"
                        ]
                    },
                    "Possible location of birth": {
                        "type": "StringField",
                        "title": "Possible location of birth",
                        "values": [
                            "Jamaica Hospital"
                        ]
                    },
                    "Related news": {
                        "type": "URLField",
                        "title": "Related news",
                        "values": [
                            ...
                        ]
                    },
                    "Summary": {
                        "type": "StringField",
                        "title": "Summary",
                        "values": [
                            "45th and current president of the United States"
                        ]
                    }
                },
                "similarity": 1.0
            },
            "updated_at": "2021-02-02T14:01:40.893990Z",
            "created_at": "2021-02-02T14:01:40.893990Z"
        },
        ],
    "has_next": false
}

In some situation you will want to have multiple watch lists, all your lists could be found here

curl -X GET\
-H "ds-api-token: [[apiKey]]"\
-H "Accept: application/json"\
https://api.dataspike.io/api/v2/sealed/watch/lists

Response Example:

    {
    "data": [
                {
                    "id": "032f6b0a-1ce1-44ea-a67b-cec9f6b37c55",
                    "user_id": 1,
                    "name": "Donald Trump lists",
                    "last_viewed": "2021-02-02T14:03:58.143Z",
                    "created_at": "2021-02-02T13:54:26.708212Z",
                    "updated_at": "2021-02-02T13:54:26.708212Z",
                    "count": 1
                },
                {
                    "id": "a004fd32-2a41-40ed-8b8e-cf0a4fa02099",
                    "user_id": 1,
                    "name": "Name 2",
                    "last_viewed": "2021-02-01T10:28:04.733Z",
                    "created_at": "2020-11-10T11:40:29.335236Z",
                    "updated_at": "2020-11-10T11:40:29.335236Z",
                    "count": 3
                },
                {
                    "id": "f853ad3d-3ff5-4eef-aadf-f1782228f122",
                    "user_id": 1,
                    "name": "Name 3",
                    "last_viewed": "2021-02-02T10:22:28.666Z",
                    "created_at": "2021-02-02T10:07:17.349569Z",
                    "updated_at": "2021-02-02T10:07:17.349569Z",
                    "count": 10
                },
    
    ]
}