Skip to main content

Selecting Parameters

This section will demonstrate the basics of selecting a parameter (in addition to an indicator) for an API request.

Endpoint and Indicator Recap​

As shown in the previous guide, an indicator is needed for each API request. Let's select population level, indicator 9:

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=9

Adding a Single Parameter​

Were the API request to be sent as above without any parameters, the API would return the population level for Canada on an abitrary date. We can easily find the population level in each province and territory by adding to the query string '&geo=provinces_territories'. The API request will then be, in curl format:

curl --location --request POST 'https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=9&geo=provinces_territories' \
--header 'x-api-key: API_KEY' \
--data-raw ''

Remember to always replace API_KEY with your unique API key to authenicate your API request. From here it is simple to add more parameters onto the end of the query string, just ensure the '&' symbol is used for each parameter. Note that some combinations of parameters (and filters - see later), will return an empty response. This response means that the Data Hub does not have the data requested. To identify where data does not exist, consider building your API requests parameter by parameter, testing the response as you go.

Single Parameter Examples​

Population Level in Canada for people aged 25-54:

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=9&age=25-54

To find the Unemployment Rate, seasonally adjusted:

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=5&seasonality=seasonally adjusted

To find the Average Weekly Wages:

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=11

Adding a Multiple parameters​

Now that you are familiar with using single parameters, we can move onto using mutiple parameters for each query. Selecting mutiple parameters is as simple as adding more query strings onto your endpoints using the '&' between each one. For example:

Employment Rate in each province and territory for people aged 15-24:

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=2&age=15-24&geo=provinces_territories

Selecting Dates​

In this documentation thus far, our API requests have been arbitary dates, which would be useless for any real request. Selecting dates of interest in the Data Hub is more tricky than other parameters, as different indicators interpret the dates differently, and the response will depend on the level of aggregation of the data (the default is monthly).

The two parameters named 'start' and 'end' allow the user to request data for a given time period. The Data Hub ingests data from its partners monthly, so selecting a present month will trigger the response for data from the previous month. Similarly, selecting dates without historical data will trigger the API to return the earliest available data.

Let's take the Unemployment Rate example: 

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=5&seasonality=seasonally adjusted

If we want to find the Unemployment Rate in September-2021, our start and end dates must fall within that month to return only that month. If our dates fall within Setember-2021 and October-2021 then the API will return 2 records, one for September and one for October. The exact day of the month is inconsequential. The following example is for Semptember (note the YYYYMMDD format):

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=5&seasonality=seasonally adjusted&start=20210901&end=20210901

Selecting Dates for Growth Indicators​

Referring to the Indicators documentation, you will see some of the indicators have 'growth' in their name. These indicators use the 'start' and 'end' parameters in a different way and perform additional calculations for the user. For example 'Job Posting Growth Year over Year', calculates the year over year growth of the 'Job Posting Counts' indicator. The calculation takes the time period selected with start and end, and compares the indicator value to 12 months prior to give a growth rate (ratio format).

The following API request returns the growth in Job Postings between February-2022 and February-2021:

curl --location --request POST 'https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=15&&start=20220201&end=20220201' \
--header 'x-api-key: API_KEY' \
--data-raw ''

The response:

{
    "data": [
        {
            "source": "Vicinity Jobs",
            "ref_date": "2022-02-28",
            "data_frequency": "monthly",
            "noc_code": "",
            "noc_level": null,
            "noc_title_en": "",
            "country": "Canada",
            "provinces_territories": null,
            "economic_regions_en": null,
            "census_division": null,
            "location": null,
            "indicator_name_en": "Year on year job postings growth",
            "indicator_value": 0.456
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "per_page": 1000,
        "total_rows": 1
    }
}