WE Data Tools

Companies API

https://api.wedatatools.com/v2/get-companies

Basic Usage

Request

The get-companies API accepts an application/x-www-form-urlencoded POST request. Authentication is provided by passing your provided API key as the “key” parameter. Additional parameters are specified in the Parameters section below.

Response

The get-companies API responds with a JSON representation of the requested data. The content of the response may vary according to the request, but a basic request will populate the “hits” key with an array of documents returned. The content of the documents can be specified according to the “includes” and “excludes” parameters specified in the Parameters section below.

Parameters

ParameterTypeDescriptionPermitted Values
keyStringYour provided API Access Key
searchStringPlaintext search. Results with a title, or additional metadata, matching the search string will be returned.
per_pageNumericResults per page. A value of -1 returns all matching results.0-10000, -1 Default: 20
pageNumericPage number.Default: 1
track_total_hitsBooleanTotal hits for a given query shows up in the meta object under total, but for performance reasons this typically caps at 10000. To remove the cap, pass true to track_total_hits.true, false Default: false
orderbyStringOrder in which to return results.date_desc, date_asc, wage_desc, wage_asc, relevance Default: relevance
start_dateDateTimeThe earliest post date from which to include postings in the result set.String formatted YYYY-MM-DD.
end_dateDateTimeThe latest post date from which to include postings in the result set.String formatted YYYY-MM-DD.
range_typeStringGoverns the type of date range to use when considering start_date and end_date.active: (default) includes postings that were actively recruiting during the specified date range.
new: includes postings that were newly posted during the specified date range.
[field]String/ArraySearch the value of a document field. See “Term Query” section.
[field]__likeString/ArrayWildcard search the value of a document field. See “Term Query” section.
[field]__notString/ArrayValue to not match for a given field. See “Term Query” section.
must_existString/ArrayField(s) that must have a value on the target document to be included in the result set.See “permitted fields”.
must_not_existString/ArrayField(s) that must not have a value on the target document to be included in the result set.See “permitted fields”.
aggregateString/ArrayProvides the “term frequency” count of a given field in the dataset. See “Aggregations” section.See “permitted fields”.
aggregate_countNumericThe top N terms to return in any aggregation function. See “Aggregations” section.Default: 100
includesString/ArrayFields to include on the return document.See “permitted fields”.
excludesString/ArrayFields to exclude on the return document – overrides “includes” in the event of overlap.See “permitted fields”.

Permitted Fields

The following fields are available on the job documents to search/aggregate/include:

Basic Data

FieldDescription
titleThe title of the employer.
contentPlaintext content associated with this job post.
excerptAs content, but limited to first 200 words.
post_dateThe date the employer was first listed.

NAICS

FieldDescription
naicsThe six-digit 2017 Canadian Industry Level NAICS code(s) associated with the employer. See North American Industry Classification System (NAICS) Canada 2017 Version 3.0.
naics_hierarchicalAs naics, but includes all applicable 2-digit, 3-digit, 4-digit, 5-digit, and 6-digit representations.
sectorAs naics, but using the 2-digit representation.

Location Data

FieldDescription
locationThe geolocation (lat + long) associated with this employer.
regionThe city/town in which this employer is headquartered.
regionsThe city/town in which this employer is headquartered, plus all related municipalities, regions, etc.
stateprovThe state/province in which this employer is headquartered.

Term Query

Any permitted field can be individually searched. The most basic way of achieving this is to pass a permitted field as a request parameter, and the value for this parameter is the string value (or array of string values) you wish to search. An example of this would be "naics": ["44831", "44832"]. There are other related parameters such as [field]__like or [field]__not that perform different types of field queries. For example, "naics__not": ["44831", "44832"] will return ensure that postings in the result set do not match either NOC 44831 or NOC 44832.

Aggregations

Aggregation queries help summarize data as metrics, percentiles, statistics, etc. There are a number of available aggregations available:

Terms

“Terms” aggregation is a bucket aggregation that will summarize the top N terms (N configurable by passing the aggregate_count parameter) for a given field in the dataset. A terms aggregation can be done on a permitted field by passing the permitted field in the aggregate parameter.

Cardinality

A “cardinality” aggregation counts the total unique values in the result set for a given permitted field. For example, "cardinality": "region" will provide a count of all unique regions in the result set.

Examples

For additional examples provided in additional programming languages, view the Postman Collection.

Get Page Of Job Postings

Request


curl --location 'https://api.wedatatools.com/v2/get-companies/' \
--data-urlencode 'key=[Your API Key]' \
--data-urlencode 'page=1' \
--data-urlencode 'per_page=5' \
--data-urlencode 'includes%5B%5D=title' \
--data-urlencode 'includes%5B%5D=region'

Response

{
    "meta": {
        "page": 1,
        "max_pages": 500,
        "returned": 20,
        "total": 10000
    },
    "hits": [
        {
            "_index": "employers",
            "_id": "684622",
            "_score": 0,
            "_source": {
                "title": "J.A Robinson Pump Service",
                "region": "Winnipeg"
            },
            "sort": [
                0,
                1713071076000
            ]
        },
        {
            "_index": "employers",
            "_id": "684621",
            "_score": 0,
            "_source": {
                "title": "Safety Express Ltd.",
                "region": "Winnipeg"
            },
            "sort": [
                0,
                1713071064000
            ]
        },
        {
            "_index": "employers",
            "_id": "684620",
            "_score": 0,
            "_source": {
                "title": "Mindrift"
            },
            "sort": [
                0,
                1713071045000
            ]
        },
        {
            "_index": "employers",
            "_id": "684619",
            "_score": 0,
            "_source": {
                "title": "Nash trucking"
            },
            "sort": [
                0,
                1713071012000
            ]
        },
        {
            "_index": "employers",
            "_id": "684618",
            "_score": 0,
            "_source": {
                "title": "Collins-Toker Agencies",
                "region": "Winnipeg"
            },
            "sort": [
                0,
                1713070993000
            ]
        }
    ]
}