Release notes June 2024

Learn about recent changes to the ArcGIS Urban API. The release date is June 26, 2024.

What's new

This section provides a summary of the most important changes in this release.

• A new cursor-based paging has been added. Now you can query multiple objects more efficiently. You can still use the old pagination using limit and offset arguments. See Cursor based paging to see an example.
• Filtering by any field in an object has been introduced. See Filtering by any field to see an example.
• The deprecated field OwnerName reached its sunset date and was removed (breaking change).

Examples

The following section provides a few examples of how to use the new Urban API features added in the June 2024 release.

Cursor based paging

This example shows how to use the new cursor based paging to query all parcels and zones of an Urban Model in batches of 5.

1. Query 5 parcels and 5 zones of an Urban Model. Add the top level cursor query. The cursor represents the current state of the 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
   query ParcelsZonesCursorQuery {
     cursor
     urbanModel(urbanModelId: "URBAN_MODEL_ID") {
       urbanDatabase {
         parcelsMeta {
           count
         }
         parcels(paging: { limit: 5 }) {
           attributes {
             GlobalID
           }
         }
         zonesMeta {
           count
         }
         zones(paging: { limit: 5 }) {
           attributes {
             GlobalID
           }
         }
       }
     }
   }

   The response should look something like this:

   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
   {
     "data": {
       "cursor": "G8AA4I3DuJnbhaY5Ni+1yB5cTbNNlUdXMJ4MnOECCaqq1bQiktAEoDqlzKL2TyLdgsXITKhwPSFkVXuE2XKbGYHejtshBrSI5habWYthUdkuB65S0khpZxq7j9u341W5",
       "urbanModel": {
         "urbanDatabase": {
           "parcelsMeta": {
             "count": 803
           },
           "parcels": [
             {
               "attributes": {
                 "GlobalID": "060db875-1bfe-4df7-a9b5-a9ae8de58ac4"
               }
             },
             {
               "attributes": {
                 "GlobalID": "e2b961e4-0fcf-4444-acc3-db2549b16c54"
               }
             },
             {
               "attributes": {
                 "GlobalID": "2d236b48-02b8-4e6e-b2bb-3589fe5a77f4"
               }
             },
             {
               "attributes": {
                 "GlobalID": "3894180e-4ffe-4490-a332-ea2e6f1857e1"
               }
             },
             {
               "attributes": {
                 "GlobalID": "039af753-9001-47bb-b47c-59e0e3a401d0"
               }
             }
           ],
           "zonesMeta": {
             "count": 465
           },
           "zones": [
             {
               "attributes": {
                 "GlobalID": "969beb82-bf5a-48bb-b17f-100e1d640ab0"
               }
             },
             {
               "attributes": {
                 "GlobalID": "5070ad55-2f0e-4de1-a24b-038ac02e80a8"
               }
             },
             {
               "attributes": {
                 "GlobalID": "98c51466-d2e1-4346-8233-4fe2c4052c42"
               }
             },
             {
               "attributes": {
                 "GlobalID": "8f061e9d-b610-4a57-9a2f-aeaa54d2cfdb"
               }
             },
             {
               "attributes": {
                 "GlobalID": "294402ff-a386-470f-919a-71d3ec380b25"
               }
             }
           ]
         }
       }
     }
   }

2. Pass the returned cursor value to the subsequent query. The next pages of results are returned using the input cursor as a starting point.

   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
   query ZonesCursorQueryNext {
     cursor(
       next: "G8AA4I3DuJnbhaY5Ni+1yB5cTbNNlUdXMJ4MnOECCaqq1bQiktAEoDqlzKL2TyLdgsXITKhwPSFkVXuE2XKbGYHejtshBrSI5habWYthUdkuB65S0khpZxq7j9u341W5"
     )
     urbanModel(urbanModelId: "da3ad4df13d84637abe3b2263f581e2f") {
       urbanDatabase {
         parcels(paging: { limit: 5 }) {
           attributes {
             GlobalID
           }
         }
         zones(paging: { limit: 5 }) {
           attributes {
             GlobalID
           }
         }
       }
     }
   }

   The response should look something like this:

   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
   {
     "data": {
       "cursor": "G8IA+I3DuJnbhaY5Ni+1yB5cTFubqS8voL4Aa8VDwbS0ZWEDDljjCAPnAeBW4I1PVLGa+7fy/QezLcUUkDAqwnYqe7We6T7DByHR2w7fLIAVNWq5RKw4JpcVuhGm5XoS0Ojc3qke",
       "urbanModel": {
         "urbanDatabase": {
           "parcels": [
             {
               "attributes": {
                 "GlobalID": "2703f2e7-3eb3-4827-8620-04083c856651"
               }
             },
             {
               "attributes": {
                 "GlobalID": "348bae63-daf2-4597-a7fb-b20b737f52d1"
               }
             },
             {
               "attributes": {
                 "GlobalID": "bdbce8d4-884a-4978-be22-ccab9d97766f"
               }
             },
             {
               "attributes": {
                 "GlobalID": "6efd287a-e071-4b5e-a369-8212fdbc4cfe"
               }
             },
             {
               "attributes": {
                 "GlobalID": "47959c58-034e-41e3-906c-3917ab6c96b9"
               }
             }
           ],
           "zones": [
             {
               "attributes": {
                 "GlobalID": "5260fb71-d62d-4779-aed9-2ec5a9c6b916"
               }
             },
             {
               "attributes": {
                 "GlobalID": "b6fad74f-085b-4630-93f0-5b2444904b19"
               }
             },
             {
               "attributes": {
                 "GlobalID": "a74018b3-e69e-4875-ab20-b309b286e95a"
               }
             },
             {
               "attributes": {
                 "GlobalID": "86f8fd3b-aa9b-4fab-bc3a-edc0e68a9476"
               }
             },
             {
               "attributes": {
                 "GlobalID": "b7b6786e-e4d7-4802-b7d6-c34cc8f2bbb4"
               }
             }
           ]
         }
       }
     }
   }

3. Iterate using the next cursor returned. When the cursor value is null, all available objects have been returned.

Filtering by any field

This example shows how to filter objects by any field.

Use the following operation to query:

• parcels in all unlocked plan scenarios on which new spaces have been generated procedurally,
• space use types in the plan, the floor height of which is less than 3.80 m.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
query Filters {
  urbanDesignDatabase(urbanDesignDatabaseId: "bc2aadfee93d4db7a58ef8f77524260c") {
    plans {
      branches(filter: { locked: false }) {
        parcels(filter: { developmentTypes: BuildingType }) {
          attributes {
            GlobalID
          }
        }
      }
      spaceUseTypes(filter: { floorHeightIsLessThan: 3.80 }) {
        attributes {
          GlobalID
        }
      }
    }
  }
}

Learn more by exploring the Docs tab in the GraphiQL interface. You can find it under the Urban API endpoint https://urban-api.arcgis.com/graphql.

Schema changes

This section describes new features and changes made to the Urban API schema.

The following field and type related to the cursor-based paging were added:

The following field and input fields related to GroundArea and GroundSpaceUseTypeID were added to ParcelAttributes:

The following field and input fields related to ExternalSublayerId were added to CriterionAttributes of the suitability tool:

The following field and input fields related to CustomElevationLayerItemId were added to BranchAttributes:

The following field and input fields related to SpaceUseTypeOrder were added to SpaceUseTypeAttributes:

The following input fields related to the new filters were added:

BranchFilterInput:

BuildingTypeFilterInput:

CriterionFilterInput:

FeedbackCategoryFilterInput:

IndicatorFilterInput:

LOD1BuildingFilterInput:

MetricFilterInput:

MetricSourceFilterInput:

MetricValueFilterInput:

OverlayFilterInput:

OverlayTypeFilterInput:

ParcelFilterInput:

PlanFilterInput:

PointSymbolFilterInput:

PolygonSymbolFilterInput:

ProjectFilterInput:

SpaceFilterInput:

SpaceUseTypeFilterInput:

StatusTypeFilterInput:

SuitabilityModelFilterInput:

ViewpointFilterInput:

ZoneFilterInput:

ZoneTypeFilterInput:

Bug fixes and improvements

• Added missing PlanningMethod filter for zoningRegulation used in the parcel explorer.
• Improved behavior of processing multiple requests simultaneously.
• Set the maximum depth of queries to 30 nodes deep.

Deprecations

• Field BranchAttributes.ModalSplit is deprecated (Removal date: 2025-06-24). This field is no longer supported. Use the metricValues field on the plan or project branch (scenario) instead.
• Removal date for field BranchAttributes.MetricValues has changed from 2024-06-26 to 2024-10-29.
• Removal date for field SpaceAttributes.MetricValues has changed from 2024-06-26 to 2024-10-29.

Breaking changes

The following previously deprecated fields have been removed.

OwnerName has been removed from BranchAttributes, PlanAttributes, ProjectAttributes and IndicatorAttributes:

• Field OwnerName (deprecated) was removed from object type BranchAttributes
  • Input field OwnerName was removed from input object type CreateBranchAttributesInput
  • Input field OwnerName was removed from input object type UpdateBranchAttributesInput
  • Enum value OwnerName (deprecated) was removed from enum BranchSortBy
• Field OwnerName (deprecated) was removed from object type PlanAttributes
  • Input field OwnerName was removed from input object type CreatePlanAttributesInput
  • Input field OwnerName was removed from input object type UpdatePlanAttributesInput
  • Enum value OwnerName (deprecated) was removed from enum PlanSortBy
• Field OwnerName (deprecated) was removed from object type ProjectAttributes
  • Input field OwnerName was removed from input object type CreateProjectAttributesInput
  • Input field OwnerName was removed from input object type UpdateProjectAttributesInput
  • Enum value OwnerName (deprecated) was removed from enum ProjectSortBy
• Field OwnerName (deprecated) was removed from object type IndicatorAttributes
  • Input field OwnerName was removed from input object type CreateIndicatorAttributesInput
  • Input field OwnerName was removed from input object type UpdateIndicatorAttributesInput

Develop has been removed from ParcelAttributes:

• Field Develop (deprecated) was removed from object type ParcelAttributes
  • Input field Develop was removed from input object type CreateParcelAttributesInput
  • Input field Develop was removed from input object type UpdateParcelAttributesInput