Agnitio data queries are performed by assembling a JSON description of the query and POSTing to the specific dataset you wish to query. We'll begin with an example request that queries the US Industry data to get the number of jobs and establishments in Latah County, ID for the full service restaurant industry:
Code Examples
curl --request POST \
--url https://agnitio.emsicloud.com/emsi.us.industry/2024.2 \
--header 'Authorization: bearer <access_token>' Example Response
{
"data": [
{
"name": "Area",
"type": "String",
"rows": [
"Latah County, ID"
]
},
{
"name": "Industry",
"type": "String",
"rows": [
"Full Service Restaurant s"
]
},
{
"name": "2023 Jobs",
"type": "Double",
"rows": [
507.7011804944611
]
},
{
"name": "Establishments.2023",
"type": "Double",
"rows": [
30.25
]
}
],
"errors": [],
"timings": [
"Build sortable results: 0.15ms",
"Sort results: 0.16ms",
"Build final response: 0.02ms",
"Parsed constraints: 2.74ms",
"Parsed metrics: 0.09ms",
"Parse query: 3.03ms",
"Generate query cartesian product: 0.07ms",
"Generate parallelization plan: 0.03ms",
"Execute parallel query at: 2.27ms",
"Overall query time: 12.35ms"
],
"totalRows": 1
}The query structure has two required fields: metrics and constraints. The metrics field is an array of objects which describe which metrics you would like queried and returned. These objects have a required name field which specifies which metric is desired. They also have an optional as field which allows you to determine what the metric is called in the response. The constraints field is an array of objects which describe how the dimensions of the dataset should be limited and aggregated. In this example, we limited the Area dimension to returning a single, arbitrary value ("Latah County, ID") defined as the aggregation of a single FIPS code ("16057"). The valid codes for a dimension can be found via the metadata endpoint in addition to other information, such as a human-readable name.
This example returned only one row but notice that the response format is column-oriented. All rows arrays in a response will have the same number of elements.
The map field in the request constraints deserves a thorough explanation. Fundamentally it maps from the codes defined by the dimension's taxonomy to user defined values that will be returned in the response. In the example above, we mapped a single user defined name ("Latah County, ID") to a single FIPS code. A more complex mapping might look like this:
{
"dimensionName": "Area",
"map": {
"Seattle Area (10 mile radius)": [
"53033",
"53035"
],
"Seattle Area (20 mile radius)": [
"53033",
"53035",
"53061",
"53053"
]
}
}This mapping will result in two response values for the Area dimension, each of which is defined by combining the data for various counties.
NOTE: If you are querying a dataset that also supports ZIP and MSA areas, you will need to prepend the area type to each metric. For example the Seattle ZIP code 98101 would become
ZIP98101. FIPS codes do not require this.
In addition to the map field, you can use a shorthand option as well known as mapLevel to roll out a given parent to all of its children as individual mappings at a specified level.
This example maplevel query is the equivalent of the following query, and can save a considerable amount of time in creating queries:
Request Body
{
"dimensionName": "Area",
"mapLevel": {
"level": 3,
"predicate":[16]
}
},Response
{
"dimensionName": "Area",
"map": {
"16003": ["16003"],
"16005": ["16005"],
"16007": ["16007"],
"16009": ["16009"],
"16011": ["16011"],
"16013": ["16013"],
"16015": ["16015"],
"16017": ["16017"],
"16019": ["16019"],
"16021": ["16021"],
"16023": ["16023"],
"16025": ["16025"],
"16027": ["16027"],
"16029": ["16029"],
"16031": ["16031"],
"16033": ["16033"],
"16035": ["16035"],
"16037": ["16037"],
"16039": ["16039"],
"16041": ["16041"],
"16043": ["16043"],
"16045": ["16045"],
"16047": ["16047"],
"16049": ["16049"],
"16051": ["16051"],
"16053": ["16053"],
"16055": ["16055"],
"16057": ["16057"],
"16059": ["16059"],
"16061": ["16061"],
"16063": ["16063"],
"16065": ["16065"],
"16067": ["16067"],
"16069": ["16069"],
"16071": ["16071"],
"16073": ["16073"],
"16075": ["16075"],
"16077": ["16077"],
"16079": ["16079"],
"16081": ["16081"],
"16083": ["16083"],
"16085": ["16085"],
"16087": ["16087"],
"16999": ["16999"]
}
},
Sorting, Offsets, and Limits
Agnitio responses can be returned in sorted order by specifying the sortBy field:
{
"metrics": [{
"name": "Jobs.2020"
}],
"constraints": [
{
"dimensionName": "Area",
"map": {
"Seattle Area (10 mile radius)": ["53033", "53035"]
}
},
...
],
"sortBy": [{
"name": "Area", "direction": "ascending"
}, {
"name": "Jobs.2020", "direction": "descending"
}]
}By default Agnitio returns all data requested, but pagination is supported via the offset and limit fields:
{
"metrics": [ ... ],
"constraints": [ ... ],
"offset": 100,
"limit": 50
}Location Quotient
Location Quotient is a measure of geographical concentration applied to summable measures such as jobs or establishments. The definition of Location Quotient (LQ) can be found here. Agnitio can calculate LQ for you on datasets with an Area dimension:
{
"metrics": [
{
"name": "Jobs.2020",
"as": "Jobs 2020 LQ",
"operation": {
"name": "LocationQuotient",
"geoparent": "0",
"along": "Industry"
}
}
],
"constraints": [
{
"dimensionName": "Area",
"map": {
"Latah County, ID": [
"16057"
]
}
},
{
"dimensionName": "Industry",
"map": {
"Full Service Restaurants": [
"722511"
]
}
}
]
}-
operation.name: identifies the desired operation as LocationQuotient -
operation.geoparent: the code of a parent value in the area dimension; use the national for a national LQ, the containing state for a state LQ, etc. -
operation.along: the dimension to perform the comparison along. UsuallyIndustryorOccupation
Shift Share
Shift Share attempts to explain what factors cause a change in a measure over time. The definition of Shift Share can be found here. Agnitio can calculate Shift Share for you on datasets with an Area dimension and metrics with a time component:
{
"metrics": [
{
"name":"Jobs.2020",
"operation":{
"name":"ShiftShare",
"geoparent":"0",
"along":"Industry",
"base": "Jobs.2010"
}
}
],
"constraints": [ ... ]
}-
operation.name: identifies the desired operation as ShiftShare -
operation.geoparent: the code of a parent value in the area dimension; use the national for a national shift share, the containing state for a state shift share, etc. -
operation.along: the dimension to perform the comparison along. UsuallyIndustryorOccupation -
operation.base: the start metric for the comparison. In the example above, we're analyzing the job change from 2010 to 2020.
Unlike all other metrics, Shift Share metrics return four response columns. These columns are named prefixed with the value of the metric's as field (if supplied) and these values: "Job Change", "Parent Growth Effect", "Mix Effect", and "Competitive Effect".