Complex Queries (BETA)

We introduce a newly available endpoint that enables API users to generate queries that are not well suited to normal REST convention. This endpoint supports nested ANDs and ORs. You can create a POST request using a custom syntax to form queries.

Creating a query

To create a new query you issue a POST request to the HTTP ENDPOINT. You can specify the dataset you wish to query as a POST parameter. You should include the required parameters of a well formed query in your POST request. The API’s response body will be a JSON hash consisting of the query results, a unique identifier for the query, and the original query from the request POST parameter.

POST https://api.mattermark.com/queries

Parameters

Each parameter is a key value pair that is submitted to the server in separate POST parameters. The parameter names (keys) are all nouns (and in the case where the part of speech is ambiguous, should be read as nouns).

Parameter Format Example Description
dataset string investors The set of data your query should be run against. See below for a complete list of available datasets.
filter hash { ‘total_funding’: { ‘gte’: 5000000 } } The criteria for which records from the data set to include in the results (more advanced examples below).
sort array of hashes [ { ‘series’: ‘desc’ }, { ‘number_of_employees’: ‘asc’ } ] The order in which results should be sorted. The sort clauses are applied in increasing index order (series desc is applied and then number_of_employees asc is applied).
per_page integer 25 The number of results to include in each page of the response.
page integer 5 The page number to returned (page 1 is the first page of results).

Required fields.

To page through results it is recommended to use the GET /quries/:query_id form of the request.

Datasets

The following is a list of the datasets available for querying. Each dataset links out to its respective documentation which will show you the available fields for filtering and sorting.

Filter

The filter POST parameter defines how to qualify if a record in the dataset should be included. For queries of any complexity this parameter will be the most sizable.

The filter is a hash. Top level keys in the hash can be boolean operators or entity properties. What constitutes an entity property can be a bit of a complex subject as, in reality it depends on the data storage implementation. The API server will attempt to parse this section and will reject invalid a query with an invalid filter - the rejection includes a message explaining what semantic errors were present in the filter.

There are two supported boolean operators: “and” and “or”. Each expects an array of hashes as its value.

A property expects either a scalar or a hash as its value. When a scalar is provided we assume that the user is implying that the ‘eq’ operator should be used (only records for which the specified property exactly matches the scalar should be returned).

For types and operators, as well as additional examples you should checkout the section MSFL.

Example

A simple query might be “show me all of the invstors with at least 100 companies in their portfolio”:

{
    "dataset": "investors",
    "filter": {
        "portfolio_size": {
            "gte": 100
        }
    }
}

Hashes, Arrays, and Enumerables

  • Within a hash you can specify a particular key exactly once.

  • Hashes are unordered. (you should not expect the order in which we iterate across hashes you send us to be deterministic)

  • There are no arrays, only enumerables.

  • An enumerable is an array in which we ignore the order of the elements. (Formally we expect a collection that responds_to :each where we may choose to process the members of that collection in an order other than what is specified.)

  • Enumerables do not have keys.

We can try and perform semantic validation of your filter on the server side but the middleware between the client and the API application code has certain expectations and failure on your part to send hashes and arrays that conform may cause unexpected behavior.

Complex Filters

Currently we support the “or” and the “and” operators as a key in a filter.

Example

Show me all of the investors in California with a portfolio of at least 100 companies

{
    "dataset": "investors",
    "filter": {
        "and": [
            { "state": "CA" },
            { "portfolio_size": { "gte": 100 } }
        ]
    }
}

Response

Status codes

For information on the various status codes used and what they mean you should checkout the errors section of these documents

Response body

Generally speaking the response body will always be a json encoded hash similar to this

{
    "query": {
        "query_id": "3a3em215",
        "dataset": "investor",
        "filter": {
            "name": "Happy Days Funding"
        }
    },
    "results": [
        {
            "investor_id": 5,
            "name": "Leet Sauceage Capitel",
            "investor_domain": "leetsauceagecapital.ca",
            "angel_co_page": "/leetsauceagecaptial",
            "location": "Canada",
            "est_most_recent_fund_size": 500000000,
            "est_most_recent_fund_date": "2015-01-02",
            "three_year_funds_offered": 4038097180,
            "three_year_funds_sold": 3031096150,            
            "type": "vc",
            "most_recent_deal": 1234,
            "number_of_deals": 214,
            "avg_deal_size": 20000000,
            "portfolio_size": 154,
            "avg_growth_score": 92,
            "city": "Toronto",
            "state": "Ontario",
            "country": "CAN",
            "website": "leetsauceagecapital.ca",
            "deals_per_company": "1.4",
            "resource_type": "investor"
        }
    ],
    "meta": {
        "total_record_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "per_page": 50
    },
    "query_id": "3a3em215"
}

You should review the response documentation for specific resources to see descriptions of all of the related response fields.

If the request fails for any reason you will receive a response with an appropriate status code and an error message in the body explaining the issue. The format for the error response is still an outstanding issue.

Paging The Results

Given a :query_id as returned from a create query request you can use this endpoint to page through the results.

HTTP Endpoint

GET https://api.mattermark.com/queries/:query_id

Supported Parameters

Parameter Format Example Description
per_page integer 25 The number of results to include in each page of the response
page integer 5 The page number to returned (like books page numbers start at 1)

Example

curl "https://api.mattermark.com/queries/23432?per_page=50&page=3"

GET an existing query

This specifically requests the query having the hash 3aEf912

GET /queries/3a3em215 HTTP/1.1
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
    "query": {
        "query_id": "3a3em215",
        "dataset": "investor",
        "filter": {
            "name": "Happy Days Funding"
        },
        "query_version": 4
    },
    "results": [
        {
            "investor_id": 5,
            "name": "Leet Sauceage Capitel",
            "investor_domain": "leetsauceagecapital.ca",
            "angel_co_page": "/leetsauceagecaptial",
            "location": "Canada",
            "est_most_recent_fund_size": 500000000,
            "est_most_recent_fund_date": "2015-01-02",
            "three_year_funds_offered": 4038097180,
            "three_year_funds_sold": 3031096150,            
            "type": "vc",
            "most_recent_deal": 1234,
            "number_of_deals": 214,
            "avg_deal_size": 20000000,
            "portfolio_size": 154,
            "avg_growth_score": 92,
            "city": "Toronto",
            "state": "Ontario",
            "country": "CAN",
            "website": "leetsauceagecapital.ca",
            "deals_per_company": "1.4",
            "resource_type": "investor"
        }
    ],
    "meta": {
        "total_record_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "per_page": 50
    },
    "query_id": "3a3em215"
}