Query Bins (Feature Service/Layer)

URL:
https://<root>/services/<serviceName>/FeatureServer/<layerId>/queryBins
Methods:
GET
Version Introduced:
11.3

Description

The queryBins operation returns an array of results divided into bins based on a numeric or date field. The response includes statistical aggregations for each bin, such as a count or avg.

The parameters property define the bins, the aggregate information returned, and the included features. The outStatistics parameter defines the information each bin will provide. Included features can be specified by providing a WHERE condition, and a spatial filter, similar to a query operation.

Bins are defined using the bin parameter. The contents of the bin parameter provide flexibility for defining bin boundaries. The bin parameter's parameters property defines the way each bin is calculated. The properties can be defined with the amount of bins present, the range of the bins, the bin boundaries or defining bins with the help of dates (e.g. fixedIntervalBin, autoIntervalBin, fixedBoundariesBin, or dateBin).

A bin can either be based on a date or on a numeric value.

Dates

Defining bins providing calendar-awareness with a fixed number of seconds, minutes, hours, days, weeks, months, quarters, or years.

Calendar-aware intervals understand that daylight savings changes the length of specific days, months have different amounts of days, and leap seconds can be tacked onto a particular year.

The starting position of the bin is the earliest moment in the specified unit. For example, each year begins at midnight of January 1. An offset inside the bin parameter can provide an offset to the starting position of the bin. This can contain a positive or negative integer value.

The offset is optional.

When dealing with dates, the unit property defines the time width of each bin, such as one year, quarter, month, day, or hour. The offset property defines an offset within that time unit. For example, if your bin unit is day, and you want bin boundaries to go from noon to noon on the next day, the offset would be 12 hours

Intervals

  • Declaring the interval. The total range will be divided into equal bins of the declared size. The number of bins will be variable depending on the whole range and the defined interval.
  • Defining the number of bins. The interval is calculated automatically by the total range divided by the number of bins.
  • Defining fixed boundaries of each bin. This allows bins of different sizes.

The interval operations can be used with numeric and date fields. Note that dates are treated as numbers in this case.

When using queryBins on a date field use Unix format for esriFieldTypeDate fields and a standardized iso-string for esriFieldTypeTimestampOffset (2023-12-15T12:00:00.000).

Request parameters

ParameterDetails

bin

(Required)

A JSON parameter that describes the characteristics of the bins, such as the size of the bin and its starting position. The size of each bin is either determined by a parameter or calculated dynamically. A bin can either be based on a date or on a numeric value. For more information and examples for supported bin types, see the Binning section below.

Syntax
Use dark colors for code blocksCopy
1
2
3
4
5
6
{
    "type": " <dateBin | fixedIntervalBin | autoIntervalBin | fixedBoundariesBin >",
    "onField": <field>,
    "parameters": <json-object>,
    "transformation": <naturalLog | squareRoot>   // optional
}
Example
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
// Date Bin example
{
  "type": "dateBin",
  "onField": "the_field",
  "parameters": {
    "number": 12,
    "unit": "hour",
    "offset": {
      "number": 5,
      "unit": "hour"
    }
  }
}

binOrder

Results can be returned in ascending or descending order. The default is ascending (ASC).

Values: ACS| DESC

outTimeReference

Defines the timezone for the calculation of bins and the output of dates.

Example
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//Date Bin syntax
{
  "timeZone": "<Windows-ID>",
  "respectsDaylightSaving": <boolean>, //true by default

  //or
  "ianaTimeZone: <IANA-ID>
}

outStatistics

The definitions for one or more field-based statistics to be calculated.

Defaults to a histogram (count on onField defined in the bin parameter) with outStatisticFieldName as frequency. By default, if a value is missing it will be ignored when performing the statistics.

The current supported spatial aggregations are CentroidAggregate, EnvelopeAggregate and ConvexHullAggregate. These statisticTypes return a geometry.

Syntax
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
outStatistics=[
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var | percentile_const |
    percentile_desc | CentroidAggregate | EnvelopeAggreagate | ConvexHullAggregate>",
    "onStatisticField": "Field1",
    "outStatisticFieldName": "Out_Field_Name1"
  },
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var | percentile_const |
    percentile_desc | CentroidAggregate | EnvelopeAggreagate | ConvexHullAggregate>",
    "onStatisticField": "Field2",
    "outStatisticFieldName": "Out_Field_Name2"

  }
]
Example
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
outStatistics=[
  {
    "statisticType": "avg",
    "onStatisticField": "age",
    "outStatisticFieldName": "AverageAge"
  }
]

where

A WHERE clause for the query filter.

SQL-92 WHERE clause syntax on the fields in the layer is supported for most data sources. Some data sources have restrictions on what is supported. Hosted feature services in ArcGIS Enterprise running on a spatiotemporal data source only support a subset of SQL-92. For example, spatiotemporal-based feature services support the like operator but do not support the not like operator or field equivalency expressions such as field1 = field2. The following is a list of supported SQL-92 with spatiotemporal-based feature services:

Use dark colors for code blocksCopy
1
2
3
4
5
( '<=' | '>=' | '<' | '>' | '=' | '!=' | '<>' | LIKE )
(AND | OR)
(IS | IS_NOT)
(IN | NOT_IN) ( '(' ( expr ( ',' expr )* )? ')' )
COLUMN_NAME BETWEEN LITERAL_VALUE AND LITERAL_VALUE

For information on how to format time and date information, see the Date-time queries section.

Example
Use dark colors for code blocksCopy
1
2
3
where=POP2000 > 350000

where=CITY_NAME = 'Barrington'

geometry

The geometry to apply as the spatial filter. The structure of the geometry is the same as the structure of the JSON geometry objects returned by the REST API. In addition to the JSON structures, you can specify the geometry of envelopes and points with a simple comma-separated syntax.

Syntax
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//JSON structures
geometryType=<geometryType>&geometry={ geometry}

//Envelope simple syntax
geometryType=esriGeometryEnvelope&geometry=<xmin>,<ymin>,<xmax>,<ymax>

//Point simple syntax
geometryType=esriGeometryPoint&geometry=<x>,<y>
Example
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//Envelop example
geometryType=esriGeometryEnvelope&geometry={xmin: -104, ymin: 35.6, xmax: -94.32, ymax: 41}

//Envelope example
geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41

//Point example
geometryType=esriGeometryPoint&geometry=-104,35.6

geometryType

The type of geometry specified by the geometry parameter. The geometry type can be an envelope, a point, a line, or a polygon. The default geometry type is an envelope.

Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope

distance

The buffer distance for the input geometries. The distance unit is specified by units. For example, if the distance is 100, the query geometry is a point, units is set to meters, and all points within 100 meters of the point are returned. The geodesic buffer is created based on the datum of the output spatial reference if it exists. If there is no output spatial reference, the input geometry spatial reference is used. Otherwise, the native layer spatial reference is used to generate the geometry buffer used in the query. This parameter only applies if supportsQueryWithDistance is true.

Syntax
Use dark colors for code blocksCopy
1
distance=<distance>
Example
Use dark colors for code blocksCopy
1
2

distance=100

units

The unit for calculating the buffer distance. If units is not specified, the default will be esriSRUnit_Foot when querying feature services in ArcGIS Enterprise, and esriSRUnit_Meter when querying feature services in ArcGIS Online. This parameter only applies if supportsQueryWithDistance is true.

Values: esriSRUnit_Meter | esriSRUnit_StatuteMile | esriSRUnit_Foot | esriSRUnit_Kilometer | esriSRUnit_NauticalMile | esriSRUnit_USNauticalMile

spatialRel

The spatial relationship to be applied to the input geometry while performing the query. The supported spatial relationships include intersects, contains, envelop intersects, within, and so on. The default spatial relationship is intersects (esriSpatialRelIntersects).

Values: esriSpatialRelIntersects | esriSpatialRelContains | esriSpatialRelCrosses | esriSpatialRelEnvelopeIntersects | esriSpatialRelIndexIntersects | esriSpatialRelOverlaps | esriSpatialRelTouches | esriSpatialRelWithin

defaultSR

The spatial reference used for input and output geometry if inSR or outSR are not specified.

inSR

The spatial reference of the input geometry. The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object. If the inSR is not specified, the geometry is assumed to be in the spatial reference of the layer.

outSR

The spatial reference of the returned geometry. The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object. If outSR is not specified, the geometry is returned in the spatial reference of the map.

quantizationParameters

A JSON object used to project the geometry onto a virtual grid, likely representing pixels on the screen. The properties of the JSON object include extent, mode, originPosition, and tolerance. For more information, see the Quantization parameters JSON properties section below.

Example
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
//upperLeft origin position
{
  "mode": "view",
  "originPosition": "upperLeft",
  "tolerance": 1.0583354500042335,
  "extent": {
    "type": "extent",
    "xmin": -18341377.47954369,
    "ymin": 2979920.6113554947,
    "xmax": -7546517.393554582,
    "ymax": 11203512.89298139,
    "spatialReference": {
      "wkid": 102100,
      "latestWkid": 3857
    }
  }
}

//lowerLeft origin position
{
  "mode": "view",
  "originPosition": "lowerLeft",
  "tolerance": 1.0583354500042335,
  "extent": {
    "type": "extent",
    "xmin": -18341377.47954369,
    "ymin": 2979920.6113554947,
    "xmax": -7546517.393554582,
    "ymax": 11203512.89298139,
    "spatialReference": {
      "wkid": 102100,
      "latestWkid": 3857
    }
  }
}

datumTransformation

This parameter applies a datum transformation while projecting geometries in the results when outSR is different than the layer's spatial reference. When specifying transformations, you need to think about which datum transformation best projects the layer (not the feature service) to the outSR and sourceSpatialReference property in the layer resource report. For a list of valid datum transformation ID values and well-known text strings, see Using spatial references. For more information on datum transformations, see the transformation parameter in the Project operation.

synatx
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
//Syntax to apply a simple transformation
datumTransformation=<wkid>

//Syntax to apply a simple transformation
datumTransformation={"wkt": "<WKT>"}

//Syntax to apply a composite transformation
datumTransformation={"geoTransforms":[{"wkid":<id>,"forward":<true|false>},
{"wkt":"<WKT>","forward":<true|false>}]}
Example
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
//Applies a simple transformation
datumTransformation=1623

//Applies a composite transformation
datumTransformation={
  "geoTransforms":[
    {
      "wkid":1088,
      "transformForward": true
    },
    {
      "wkid": "GEOGTRAN[\"S_JTSK_To_WGS_1984_1\",GEOGCS[\"GCS_S_JTSK\",
      DATUM[\"D_S_JTSK\",SPHEROID[\"Bessel_1841\",6377397.155,299.1528128]],
      PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",0.0174532925199433]],
      GEOGCS[\"GCS_WGS_1984\",DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_1984\",
      6378137.0,298.257223563]],PRIMEM[\"Greenwich\",0.0],
      UNIT[\"Degree\",0.0174532925199433]],METHOD[\"Position_Vector\"],
      PARAMETER[\"X_Axis_Translation\",570.8],PARAMETER[\"Y_Axis_Translation\",85.7],
      PARAMETER[\"Z_Axis_Translation\",462.8],PARAMETER[\"X_Axis_Rotation\",4.998],
      PARAMETER[\"Y_Axis_Rotation\",1.587],PARAMETER[\"Z_Axis_Rotation\",5.261],
      PARAMETER[\"Scale_Difference\",3.56]]",
      "transformForward":false
    }
  ]
}

lowerBoundaryAlias

This parameter changes the default name of the lower boundary property returned in the response to a user-specified name. The boundary property indicates the value at the edge of each bin that is returned in a response. Unless changed using the lowerBoundaryAlias parameter, this field will be named lowerBoundary by default.

Example
Use dark colors for code blocksCopy
1
lowerBoundaryAlias=temperatureBinValueLower

upperBoundaryAlias

This parameter changes the default name of the upper boundary property returned in the response to a user-specified name. The boundary property indicates the value at the edge of each bin that is returned in a response. Unless changed using the upperBoundaryAlias parameter, this field will be named upperBoundary by default.

Example
Use dark colors for code blocksCopy
1
upperBoundaryAlias=temperatureBinValueUpper

async

Specifies whether the operation will run synchronously (false) or asynchronously (true).

Values: true | false

f

The response format. The default format is html.

Values: html | json | pjson

Support parameters

The support parameters defined in queryBinsCapabilities define which queryBins operation is allowed in the dialect of the feature layer. The following support parameters are defined:

  • supportsDateBin
  • supportsFixedIntervalBin
  • supportsAutoIntervalBin
  • supportsFixedBoundariesBin
  • supportedStatisticTypes (provides a list of the supported statistics operations for the dialect)

Binning

There are four different binning operations that all work slightly differently, especially when it comes to boundaries. It is important to understand what each operations goal is to understand how the binning works and how the boundaries are defined.

autoIntervalBin

For Auto Interval the focus lies in the number of bins. The size of the bins will be calculated using the range of the dataset and the number of bins. The last item of the range will be added to the last bin.

For example, in a dataset having items 10, 34, 56 and 88, and a desired number of bins of 3, this would be the distribution:

  1. [10 – 36]: 10, 34
  2. [36 – 62]: 56
  3. [62 – 88]: 88
Syntax
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
{
  "type": "autoIntervalBin",
  "onField": < numericField | dateField >,
  "parameters": {
    "numberOfBins": <integer>,
    "start": < numeric | date >,
    "end": < numeric | date >
  }
}
Example
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
{
  "type": "autoIntervalBin",
  "onField": "the_field",
  "parameters": {
    "numberOfBins": 10,
    "start": 0,
    "end": 12500.5
  }
}

Output

The output of the bins always has a lower boundary and an upper boundary. The lower boundary is inclusive and the upper boundary is exclusive. The only exception to this is the upper boundary of the last bin, which is also inclusive.

In the following example items 0, 10, 40 and 99 would be in bin 1. Item 100 would be in bin 2. But item 300 would be in bin 3:

  1. 0 (inclusive) – 100 (exclusive)
  2. 100(inclusive) – 200 (exclusive)
  3. 200 (inclusive) – 300 (inclusive)

While the output works the same for each binning operation, the way the bins are calculated differs.

Date-time queries

Date and time format

The INTERVAL syntax can be used in place of the date-time queries and is standardized across all map and feature services. The INTERVAL syntax can be used to specify either the current date or timestamp in the query:

Use dark colors for code blocksCopy
1
2
3
4
5
//Date
<DateField> >= CURRENT_DATE -+ INTERVAL '<IntervalValue>' <TimeStampFormat>

//Timestamp
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL '<IntervalValue>' <TimeStampFormat>

For the syntax demonstrated above, you can interchange the CURRENT_DATE and CURRENT_TIMESTAMP values. Both can be used with + or - of INTERVAL values.

The examples below outline the different ways in which the INTERVAL syntax can be modified for the purposes of your query:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
//'DD' Day
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD' DAY

//'HH' Hour
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'HH' HOUR

//'MI' Minute
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'MI' MINUTE

//'SS(.FFF)' Second
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'SS(.FFF)' SECOND

//'DD HH' DAY TO HOUR
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD HH' DAY TO HOUR

//'DD HH:MI' DAY TO MINUTE
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD HH:MI' DTY TO MINUTE

//'DD HH:MI:SS(.FFF)' DAY TO SECOND
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD HH:MI:SS(.FFF)' DAY TO SECOND

//'HH:MI' HOUR TO MINUTE
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'HH:MI' HOUR TO MINUTE

//'HH:SS(.FFF)' HOUR TO SECOND
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'HH:SS(.FFF)' HOUR TO SECOND

//'MI:SS(.FFF)' MINUTE TO SECOND
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'MI:SS(.FFF)' MINUTE TO SECOND

To demonstrate the INTERVAL format, the example below uses the INTERVAL syntax to query data gathered over the 3 days, 5 hours, 32 minutes, and 28 seconds:

Use dark colors for code blocksCopy
1
DateField >= CURRENT_TIMESTAMP - INTERVAL '3 05:32:28' DAY TO SECOND

Percentile statistic type

The percentile statisticType is supported if the supportsPercentileStatistics layer property (in advancedQueryCapabilities ) is true . The percentile indicates the value below or above which a given percentage of values in a group of data values falls. For example, the ninetieth percentile (value 0.9) is the value below which 90 percent of the data values may be found. For percentile statistics, there are two statisticTypes , PERCENTILE_DISC (discrete) and PERCENTILE_CONT (continuous). Discrete returns a data value from within that dataset while continuous is an interpolated value.

The orderBy statistic parameter can also be used to calculate the percentile. For example, in a set of 10 values from 1 to 10, the percentile value for 0.9 with orderBy set as ascending (ASC ) is 9, while the percentile for value 0.9 with orderBy set as descending (DESC ) is 2. The default is ASC .

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[
  {
    "statisticType": "<PERCENTILE_CONT | PERCENTILE_DISC>",
    "statisticParameters": {
      "value": percentile_value,
      "orderBy": "<ASC | DESC>"
    },
    "onStatisticField": "Field1",
    "outStatisticFieldName": "Out_Field_Name1"
  },
  {
    "statisticType": "<PERCENTILE_CONT | PERCENTILE_DISC>",
    "statisticParameters": {
      "value": percentile_value,
      "orderBy": "<ASC | DESC>"
    },
    "onStatisticField": "Field2",
    "outStatisticFieldName": "Out_Field_Name2"
  }
]

Example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[
  {
    "statisticType": "PERCENTILE_CONT",
    "statisticParameters": {
      "value": 0.9
    },
    "onStatisticField": "NEAR_DIST",
    "outStatisticFieldName": "pop90_cont"
  },
  {
    "statisticType": "PERCENTILE_DISC",
    "statisticParameters": {
      "value": 0.9,
      "orderBy": "DESC"
    },
    "onStatisticField": "population",
    "outStatisticFieldName": "pop90_desc"
  }
]

Quantization parameters JSON properties

PropertyDescription

extent

An extent defining the quantization grid bounds. Its spatialReference matches the input geometry spatial reference if one is specified for the query. Otherwise, the extent will be in the layer's spatial reference.

mode

Geometry coordinates are optimized for viewing and displaying of data. The view value specifies that geometry coordinates should be optimized for viewing and displaying of data. The edit value specifies that full-resolution geometries should be returned, which can support lossless editing.

Value: view | edit

originPosition

Integer coordinates will be returned relative to the origin position defined by this property value. The default value is upperLeft .

Values: upperLeft | lowerLeft

tolerance

The tolerance is the size of one pixel in the outSpatialReference units. This number is used to convert the coordinates to integers by building a grid with resolution matching the tolerance. Each coordinate is then snapped to one pixel on the grid. Consecutive coordinates snapped to the same pixel are removed to reduce the overall response size.

The units of tolerance are defined by outSpatialReference. If the outSpatialReference is not specified, tolerance is assumed to be in the unit of the spatial reference of the layer. If the tolerance is not specified, the maxAllowableOffset is used.

If mode is set to edit , the tolerance is always set to the full-resolution tolerance of the spatial reference regardless of what is passed in or set for the maxAllowableOffset . If mode is set to view and the tolerance and maxAllowableOffset are not specified, a default 10,000 by 10,000 grid is used.

Example usages

The following examples demonstrate different ways to modify the features returned by the queryBins operation.

Example one

Suppose you want to find out what the average income is for each generation in the US. You'd like to define your bins as the different age groups (2012-1997-1981-1965-1955-1946-1928-1922)

Since the bins do not all have the same size we will use the bin type boundaries. Since you're looking at year of birth, you'll use a field named yearOfBirth as the onField.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
Bin={
  "type": "fixedBoundariesBin",
  "onField": "yearOfBirth",
  "parameters": {
    "boundaries": [1922,1928,1946,1955,1965,1981,1997,2012]
  }
}

You can define what information is returned using the outStatistics parameters. For analysis, you're interested in seeing the counts and averages of the data. This will return the amount of people in the generation and the average income:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
outStatistics = [
  {
    "statisticType": "count",
    "onStatisticField": "yearOfBirth",
    "outStatisticFieldName": "sum_of_people"
  },
  {
    "statisticType": "avg",
    "onStatisticField": "yearlyIncome",
    "outStatisticFieldName": "avg_income"
  }
]

Now you have the basics of your desired result. You can further refine results by providing filters on the data, such as filtering certain products using a where filter, or using spatial filters to look at regional data.

Example URL

The following is a sample GET request for the queryBins operation, demonstrating the workflow discussed above:

Use dark colors for code blocksCopy
1
https://machine.domain.com/webadaptor/rest/services/Hosted/Sales21/FeatureServer/0/queryBins?bin={"type":"fixedBoundariesBin","onField":"yearOfBirth","parameters":{"boundaries":[1922,1928,1946,1955,1965,1981,1997,2012]}}&outStatistics=[{"statisticType":"count","onStatisticField":"yearOfBirth","outStatisticFieldName":"sum_of_people"},{"statisticType":"avg","onStatisticField":"yearlyIncome","outStatisticFieldName":"avg_income"}]&f=pjson

JSON Response example

The following JSON response is a sample of the information returned from the request:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
{
  "features": [
    {
      "attributes": {
        "lowerBoundary": 1922,
        "upperBoundary": 1928,
        "sum_of_people": 54,
        "avg_income": 0
      }
    },
    {
      "attributes": {
        "lowerBoundary": 1928,
        "upperBoundary": 1946,
        "sum_of_people": 664000,
        "avg_income": 0
      }
    },
    {
      "attributes": {
        "lowerBoundary": 1946,
        "upperBoundary": 1955,
        "sum_of_people": 18226800,
        "avg_income": 41969
      }
    },
    {
      "attributes": {
        "lowerBoundary": 1955,
        "upperBoundary": 1965,
        "sum_of_people": 68325600,
        "avg_income": 71183
      }
    },
    {
      "attributes": {
        "lowerBoundary": 1965,
        "upperBoundary": 1981,
        "sum_of_people": 65105200,
        "avg_income": 102512
      }
    },
    {
      "attributes": {
        "lowerBoundary": 1981,
        "upperBoundary": 1997,
        "sum_of_people": 71944400,
        "avg_income": 84563
      }
    },
    {
      "attributes": {
        "lowerBoundary": 1997,
        "upperBoundary": 2012,
        "sum_of_people": 69321600,
        "avg_income": 42335
      }
    }
  ],
  "exceededTransferLimit": false,
  "fields": [
    {
      "defaultValue": null,
      "name": "lowerBoundary",
      "length": 131089,
      "alias": "lowerBoundary",
      "type": "esriFieldTypeInteger"
    },
    {
      "defaultValue": null,
      "name": "upperBoundary",
      "length": 131089,
      "alias": "upperBoundary",
      "type": "esriFieldTypeInteger"
    },
    {
      "defaultValue": null,
      "name": "sum_of_people",
      "length": 20,
      "alias": "sum_of_people",
      "type": "esriFieldTypeBigInteger"
    },
    {
      "defaultValue": null,
      "name": "avg_income",
      "length": 131089,
      "alias": "avg_income",
      "type": "esriFieldTypeDouble"
    }
  ]
}

Example two

You want to create a histogram graph again for income date but this time you want to showcase how many people earn how much in steps of $5000. That means the onField will be annual_income. We will choose a bin with an interval of 5000, starting at 0 and capping it at 200,000. Since histogram is the default, we don’t need the outStatistics parameter.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
Bin={
  "type": "fixedIntervalBin",
  "onField": "annual_income",
  "parameters": {
    "interval": 50000,
    "start": 0,
    "end": 200000
  }
}

Example URL

The following is a sample GET request for the queryBins operation, demonstrating the workflow discussed above:

Use dark colors for code blocksCopy
1
https://machine.domain.com/webadaptor/rest/services/Hosted/AZTempRec/0/queryBins?bin={"type":"fixedIntervalBin","onField":"annual_income","parameters":{"interval":50000,"start":0,"end":200000}}&f=pjson

JSON Response example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "features": [
    {
      "attributes": {
        "lowerBoundary": 0,
        "upperBoundary": 50000,
        "frequency": 105475
      }
    },
    {
        "attributes ": {
        "lowerBoundary": 50000,
        "upperBoundary": 100000,
        "frequency": 2849115
      }
    },
    {
        "attributes": {
        "lowerBoundary":100000,
        "upperBoundary": 150000,
        "frequency": 1568721
      }
    },
    {
        "attributes": {
        "lowerBoundary": 150000,
        "upperBoundary": 200000,
        "frequency": 1053475
      }
    }
  ],
  "exceededTransferLimit": false,
  "fields": [
    {
      "defaultValue": null,
      "name": "boundary",
      "length": 131089,
      "alias": "boundary",
      "type": "esriFieldTypeDouble"
    },
    {
      "defaultValue": null,
      "name": "frequency",
      "length": 20,
      "alias": "frequency",
      "type": "esriFieldTypeBigInteger"
    }
  ]
}

Example three

Suppose you want to do a daily breakdown of sales for the month of January 2021. You'd like to define your days as starting at 8:00am.

You'd start by defining the bins. You want a breakdown of single days, so you'll use the unit type day. By default, daily bins start at 00:00:00 UTC. To get the desired bins, you want to shift the time forward 8 hours by providing an offset. This gives you the bin definition. Since you're looking at sales, you'll use the dateSold field as the onField.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
Bin={
  "type": "dateBin",
  "onField": "dateSold",
  "parameters": {
    "unit": "day",
    "start": 1609516800000,
    "end": 1612195199999,
    "offset": {
      "number": 8,
      "unit": "hour"
    }
  }
}

You're not sure that the data stretches across every day of the month. The last two days fall on a weekend, and the stores are only open on weekdays. If you only have data to the January 29, you could miss the last two days from appearing in the result, but you would instead like those to show up as days with zero sales. To ensure that all days in January are displayed, as well as restricting the included features to only January (and to 7:59 am on February 1), you can define a time extent on the data from January 1 at 8:00 a.m. to February 1 at 7:59:59:9999 a.m.

Note that if you wish to restrict the days to January, but to not include the last two days, you can use the where parameter.

You can define what information is returned using the statistics parameters. For analysis, you're interested in seeing the counts and averages of the data. This will return the count of items and the average sales price:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
outStatistics=[
  {
    "statisticType": "count",
    "onStatisticField": "objectid",
    "outStatisticFieldName": "item_sold_count"
  },
  {
    "statisticType": "avg",
    "onStatisticField": "price",
    "outStatisticFieldName": "avg_daily_revenue"
  }
]

Now you have the basics of your desired result. You can further refine results by providing filters on the data, such as filtering certain products using a where filter, or using spatial filters to look at regional data.

Example URL

The following is a sample GET request for the queryBins operation, that demonstrates the workflow discussed above:

Use dark colors for code blocksCopy
1
https://machine.domain.com/webadaptor/rest/services/Hosted/Sales21/FeatureServer/0/queryBins?bin={"type":"dateBin","onField":"dateSold","parameters":{"unit":"day","offset":{"number":8,"unit":"hour"},"start":1609516800000,"end":1612195199999}}& outStatistics=[{"statisticType": "count","onStatisticField": "objectid","outStatisticFieldName": "item_sold_count"},{"statisticType": "avg","onStatisticField": "price","outStatisticFieldName": "avg_daily_revenue "}]&where=&binOrder=&geometry=&inSR=&outSR=&spatialRel=esriSpatialRelIntersects&returnCentroid=false&quantizationParameters=&resultOffset=&resultRecordCount=&returnExceededLimitFeatures=false&f=pjson

JSON Response example

The following JSON response is a sample of the information returned from the request:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "features": [
    {
      "attributes": {
        "lowerBoundary": 1609516800000,
        "upperBoundary": 1609603200000,
        "avg_daily_revenue": 300.40,
        "item_sold_count": 79
      }
    },
    {
      "attributes": {
        "lowerBoundary": 1609603200000,
        "upperBoundary": 1612195199999,
        "avg_daily_revenue": null,
        "item_sold_count": 0
      }
    }
  ],
  "fields": [
    {
      "name": "lowerBoundary",
      "type": " esriFieldTypeDate"
    },
    {
      "name": "upperBoundary",
      "type": "esriFieldTypeDate"
    },
    {
      "name": "item_sold_count",
      "alias": "item_sold_count",
      "type": "esriFieldTypeInteger"
    },
    {
      "name": "avg_daily_revenue",
      "alias": "avg_daily_revenue",
      "type": "esriFieldTypeDouble"
    }
  ]
}

Example four

You want to create yearly bins for Arizona temperature data, beginning from 1/1/1976 and ending on the final date contained in the record data, starting at 5:00 a.m. You want to include only data that contains a temperature reading for each year together with the centroid. To achieve this, the following information is included in your request:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

bin={
  "type": "dateBin",
  "onField": "recorded_date",
  "parameters": {
    "unit": "year",
    "offset": {
      "number": 5,
      "unit": "hour"
    },
    "start": 189331200000
  }
}

outTimeReference ={
  "timeZone": "Mountain Standard Time",
  "respectsDaylightSaving": true
}


outStatistics=[
  {
    "statisticType": "count",
    "onStatisticField": "temperature",
    "outStatisticFieldName": "results_count"
  },
  {
    "statisticType": "avg",
    "onStatisticField": "temperature",
    "outStatisticFieldName": "temperature_avg"
  }
]

where=temperature is not null

returnCentroid=true

Example URL

The following is a sample request URL for the workflow discussed above:

Use dark colors for code blocksCopy
1
https://machine.domain.com/webadaptor/rest/services/Hosted/AZTempRec/0/ queryBins?bin={"type":"dateBin","onField":"recorded_date","parameters":{"unit":"year","offset":{"number":5,"unit":"hour"},"start":189331200000}}& outStatistics=[{"statisticType": "count","onStatisticField": "temperature","outStatisticFieldName": "results_count"},{"statisticType": "avg","onStatisticField": "temperature","outStatisticFieldName": "temperature_avg"}]&outTimeReference={"timeZone":"Mountain Standard Time","respectsDaylightSaving":"true"}&where=temperature is not null &binOrder=&geometry=&inSR=&outSR=&spatialRel=esriSpatialRelIntersects &returnCentroid=true &quantizationParameters=&resultOffset=&resultRecordCount=&returnExceededLimitFeatures=false&f=pjson

JSON Response example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "features": [
    {
      "centroid": {
        "x": -84.02204922365141,
        "y": 35.93228062956047
      },
      "attributes": {
        "lowerBoundary": "1976-01-01T05:00:00-07",
        "upperBoundary": "1977-01-01T05:00:00-07",
        "temperature_avg": 59.82,
        "results_count": 60964
      }
    },
    {
      "centroid": {
        "x": -84.32106073325814,
        "y": 35.930795102124708
      },
      "attributes": {
        "lowerBoundary": "1977-01-01T05:00:00-07",
        "upperBoundary": "1978-01-01T05:00:00-07",
        "temperature_avg": 59.77,
        "results_count": 67719
      }
    },
    "fields": [
      {
        "name": "lowerBundary",
        "type": "esriFieldTypeTimestampOffset"
      },
      {
        "name": "upperBundary",
        "type": "esriFieldTypeTimestampOffset"
      },
      {
        "name": "results _count",
        "alias": "results _count",
        "type": "esriFieldTypeInteger"
      },
      {
        "name": "temperature_avg",
        "alias": "temperature_avg",
        "type": "esriFieldTypeDouble"
      }
    ],
    "geometryType": "esriGeometryPoint"
  ]
}

JSON Response syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "fields": [
    {
      "name": "<fieldName1>",
      "type": "<fieldType1>",
      "alias": "<fieldAlias1>"
    },
    {
      "name": "<fieldName2>",
      "type": "<fieldType2>",
      "alias": "<fieldAlias2>"
    }
  ],
  "features": [
    <feature1>,
    <feature2>
  ]
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.