--- title: "Creates a catalog" method: POST path: "/catalogs" tags: ["config"] --- # Creates a catalog `POST /catalogs` Creates a new catalog with the specified layers. The create catalog operation runs asynchronously. Once you've submitted the catalog for creation, you'll receive a randomly generated token that you can use to monitor the status of the operation. ## Query parameters - `billingTag` string ## Request body - CreateCatalog — Describes the configuration of the catalog including its layer definitions. - `id` string, required — The ID to use when referring to this catalog programmatically. Catalog IDs must be unique across all catalogs in the Open Location Platform. Do not put private information in the catalog ID. The catalog ID forms a portion of the catalog''s HERE Resource Name (HRN), and HRNs are visible to other users. Only lowercase alphanumeric characters (a-z), digits (0-9) and dash (-) are allowed in a catalog ID and the first and the last character must be a-z or 0-9. - `name` string, required — The short name for the catalog - `summary` string, required — A one-sentence summary of the catalog. You can see this summary when you browse a list of catalogs on the platform portal. - `description` string, required — A detailed description of the catalog and what it contains. This information appears on the 'Overview' tab when you open a catalog in the platform portal. - `tags` string[] — Some keywords that help to find the catalog when searching in the platform portal - `layers` union[] — The layers in the catalog - union - CreateVersionedLayer — Describes properties of a catalog versioned layer. - `id` string, required — The ID to use when referring to this layer programmatically. - `name` string, required — The display name for the layer. - `summary` string, required — A one-sentence summary of the layer. You can see this summary when you browse a list of layers on the platform portal. - `description` string, required — A detailed description of the layer and what it contains. This information appears on the 'Overview' tab when you open a layer in the platform portal. - `coverage` Coverage — The geographic area that this layer covers - `adminAreas` string[] — A list of ISO 3166 two-letter codes for countries and regions optionally followed by up to three characters codes for subdivisions, such as 'DE', 'PL', or 'CN-HK'. - `schema` Schema — Describes a HRN for the layer schema. Can be updated by the user for any kind of layer. - `hrn` string - `partitioningScheme` 'generic' | 'heretile' — The name of the partitioning scheme for the layer - `partitioning` Partitioning — Describes the way in which data is partitioned within the layer. - `scheme` 'generic' | 'heretile', required — The name of the partitioning scheme for the layer - `tileLevels` integer[] — A list of quadtree tile levels which contain data partitions. Only used if the partitioningScheme is heretile. - `contentType` string, required — The MIME type of the data is stored in this layer. Cannot be updated for `objectstore` and `interactivemap` layers. The default value for interactivemap layer is `application/geo+json` because the data is stored and retrieved in GeoJSON format compatible with RFC-7946 (https://www.rfc-editor.org/rfc/rfc7946). - `contentEncoding` 'gzip' — Identifies whether the data is compressed. Can be updated only for the stream layer. - `tags` string[], required — Some keywords that help to find the layer when searching in the platform portal - `billingTags` string[], required — List of billing tags a free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alphanumeric ASCII characters [A-Za-z0-9] and the following special characters: - _ (except first and last character). - `digest` 'MD5' | 'SHA-1' | 'SHA-256' — The digest algorithm used to calculate the checksum for the partitions in this layer. If specified, you can assume that all partitions in the layer, at every version, were calculated using this algorithm. Note that it is the responsibility of the data publisher to use this algorithm to calculate partition checksums. The HERE platform services do not verify that the specified algorithm was actually used. - `crc` 'CRC-32C' — The CRC algorithm used to calculate the checksum for the partitions in this layers - `layerType` 'versioned', required — The type of data availability that this layer provides - `secureHandles` boolean — Indicates if the layer metadata and blob are in a mode that secure dataHandles support. It supports only heretile layer partitioning. The produced dataHandles contain a reference partitionId and a secure signature, for example '2423589347~5945c961-e74d-478f-8afe-da53cf4189e3~EAAQuWgWdiwktzMKEeweZA-6HteHy38hXR_NY-qpeSamlJc'." - `subsetRestrictions` boolean — This field is deprecated on the catalog level. Use subsetRestrictions on the layer level only. Indicates if the subsetRestrictions for a layer is enabled or not. Supported only for layers with heretile partitioning. After deprecation setting subsetRestrictions on the catalog level takes no effect. It will simply be ignored. - `versionedLayerProperties` VersionedLayerPropertiesInPost - `extends` ExtendsWithVersion — Extension definition that allows a layer's content to be based on an existing layer. Entities in the extension layer override features with the same ID in the extended layer. - `catalogHrn` string, required — Catalog HRN of the layer being extended. - `layerId` string, required — Layer ID of the layer being extended. - `baseVersion` integer — The version of the extended catalog. If provided, then empty publication with version 0 will be created. - `encryptionType` 'hereEncryption' | 'cloudEncryption' — Defines type of encryption to apply for data at rest. 'hereEncryption' is default and ensures that encryption keys are managed by HERE, 'cloudEncryption' uses standard cloud providers encryption mechanism like AWS S3 Bucket keys or similar. - CreateVolatileLayer — Describes properties of a catalog volatile layer. - `id` string, required — The ID to use when referring to this layer programmatically. - `name` string, required — The display name for the layer. - `summary` string, required — A one-sentence summary of the layer. You can see this summary when you browse a list of layers on the platform portal. - `description` string, required — A detailed description of the layer and what it contains. This information appears on the 'Overview' tab when you open a layer in the platform portal. - `coverage` Coverage — The geographic area that this layer covers - `adminAreas` string[] — A list of ISO 3166 two-letter codes for countries and regions optionally followed by up to three characters codes for subdivisions, such as 'DE', 'PL', or 'CN-HK'. - `schema` Schema — Describes a HRN for the layer schema. Can be updated by the user for any kind of layer. - `hrn` string - `partitioningScheme` 'generic' | 'heretile' — The name of the partitioning scheme for the layer - `partitioning` Partitioning — Describes the way in which data is partitioned within the layer. - `scheme` 'generic' | 'heretile', required — The name of the partitioning scheme for the layer - `tileLevels` integer[] — A list of quadtree tile levels which contain data partitions. Only used if the partitioningScheme is heretile. - `contentType` string, required — The MIME type of the data is stored in this layer. Cannot be updated for `objectstore` and `interactivemap` layers. The default value for interactivemap layer is `application/geo+json` because the data is stored and retrieved in GeoJSON format compatible with RFC-7946 (https://www.rfc-editor.org/rfc/rfc7946). - `contentEncoding` 'gzip' — Identifies whether the data is compressed. Can be updated only for the stream layer. - `tags` string[], required — Some keywords that help to find the layer when searching in the platform portal - `billingTags` string[], required — List of billing tags a free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alphanumeric ASCII characters [A-Za-z0-9] and the following special characters: - _ (except first and last character). - `ttlHours` integer — The expiry time in hours for data in this layer. Data is automatically removed after the specified time limit has elapsed. - `ttl` integer — The expiry time in milliseconds for data in this layer. Data is automatically removed after the specified time limit has elapsed. For volatile layers, the TTL value must be between 60000 (1 minute) and 604800000 (7 days). For stream layers the TTL value must be between 600000 (10 minutes) and 259200000 (72 hours). Can be updated for stream and index layers. - `digest` 'MD5' | 'SHA-1' | 'SHA-256' — The digest algorithm used to calculate the checksum for the partitions in this layer. If specified, you can assume that all partitions in the layer, at every version, were calculated using this algorithm. Note that it is the responsibility of the data publisher to use this algorithm to calculate partition checksums. The HERE platform services do not verify that the specified algorithm was actually used. - `crc` 'CRC-32C' — The CRC algorithm used to calculate the checksum for the partitions in this layers - `volume` VolatileVolume — Describes a catalog volatile volume to be used for storing the layer's data content. Specifies volatile properties values if they are not provided. - `volumeType` 'volatile', required - `maxMemoryPolicy` 'failOnWrite' | 'replaceLessRecentlyUsedKey' — Defines a keys eviction policy when the memory limit for volatile layer is reached. - `volatileProperties` VolatileProperties — Properties that define the scale of the volatile layer. - `dataRedundancy` 'single-instance' | 'multi-instance' — Volatile storage provision mode. - `storageCapacityMb` integer, required — Capacity of volatile storage in MB. Value should be divisible by 100. The minimum is 100, the maximum is 21000 MB. - `layerType` 'volatile', required — The type of data availability that this layer provides - `secureHandles` boolean — Indicates if the layer metadata and blob are in a mode that secure dataHandles support. It supports only heretile layer partitioning. The produced dataHandles contain a reference partitionId and a secure signature, for example '2423589347~5945c961-e74d-478f-8afe-da53cf4189e3~EAAQuWgWdiwktzMKEeweZA-6HteHy38hXR_NY-qpeSamlJc'." - `subsetRestrictions` boolean — This field is deprecated on the catalog level. Use subsetRestrictions on the layer level only. Indicates if the subsetRestrictions for a layer is enabled or not. Supported only for layers with heretile partitioning. After deprecation setting subsetRestrictions on the catalog level takes no effect. It will simply be ignored. - CreateStreamLayer — Describes properties of a catalog stream layer. - `id` string, required — The ID to use when referring to this layer programmatically. - `name` string, required — The display name for the layer. - `summary` string, required — A one-sentence summary of the layer. You can see this summary when you browse a list of layers on the platform portal. - `description` string, required — A detailed description of the layer and what it contains. This information appears on the 'Overview' tab when you open a layer in the platform portal. - `coverage` Coverage — The geographic area that this layer covers - `adminAreas` string[] — A list of ISO 3166 two-letter codes for countries and regions optionally followed by up to three characters codes for subdivisions, such as 'DE', 'PL', or 'CN-HK'. - `schema` Schema — Describes a HRN for the layer schema. Can be updated by the user for any kind of layer. - `hrn` string - `partitioningScheme` 'generic' | 'heretile' — The name of the partitioning scheme for the layer - `partitioning` Partitioning — Describes the way in which data is partitioned within the layer. - `scheme` 'generic' | 'heretile', required — The name of the partitioning scheme for the layer - `tileLevels` integer[] — A list of quadtree tile levels which contain data partitions. Only used if the partitioningScheme is heretile. - `contentType` string, required — The MIME type of the data is stored in this layer. Cannot be updated for `objectstore` and `interactivemap` layers. The default value for interactivemap layer is `application/geo+json` because the data is stored and retrieved in GeoJSON format compatible with RFC-7946 (https://www.rfc-editor.org/rfc/rfc7946). - `contentEncoding` 'gzip' — Identifies whether the data is compressed. Can be updated only for the stream layer. - `tags` string[], required — Some keywords that help to find the layer when searching in the platform portal - `billingTags` string[], required — List of billing tags a free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alphanumeric ASCII characters [A-Za-z0-9] and the following special characters: - _ (except first and last character). - `ttlHours` integer — The expiry time in hours for data in this layer. Data is automatically removed after the specified time limit has elapsed. - `ttl` integer — The expiry time in milliseconds for data in this layer. Data is automatically removed after the specified time limit has elapsed. For volatile layers, the TTL value must be between 60000 (1 minute) and 604800000 (7 days). For stream layers the TTL value must be between 600000 (10 minutes) and 259200000 (72 hours). Can be updated for stream and index layers. - `volume` DurableVolume — Describes a catalog durable volume to be used for storing the layer's data content. - `volumeType` 'durable', required - `streamProperties` StreamProperties — Properties that define the scale of the required streaming layer. It is recommended to provide all 3 properties when creating a streaming layer. Either combination of `dataInThroughputKbps` and `dataOutThroughputKbps` or `parallelization` is required. `dataInThroughputKbps` and `dataOutThroughputKbps` can only be values multiple of 100. For instance, the value 33200 is valid while 32250 is not. Default values for missing field(s) will be calculated according to the following formulas: `1 parallelization = 1000 dataInThroughputKbps`, `1 parallelization = 2000 dataOutThroughputKbps`. - `dataInThroughputKbps` integer — Maximum throughput for incoming data expressed in kilobytes per second. Throttling occurs when the inbound rate exceeds the maximum inbound throughput. The default is 1000 KBps. The minimum is 100 KBps, the maximum is 32800 KBps. Can only be multiple of 100 KBps. Can be updated by the user. - `dataOutThroughputKbps` integer — Maximum throughput for outgoing data expressed in kilobytes per second. Throttling occurs when the total outbound rate to all consumers exceeds the maximum outbound throughput. The default is 4000 KBps. The minimum is 100 KBps, the maximum is 65500 KBps. Can only be multiple of 100 KBps. Can be updated by the user. - `parallelization` integer — Number of stream partitions that maps to a Kafka topic partition. The maximum parallelism at which your application may run is determined by the maximum number of stream partitions of the input stream layer the application is reading from in its processing topology. The default is 4. The maximum is 32. - `layerType` 'stream', required — The type of data availability that this layer provides - CreateIndexLayer — Describes properties of a catalog index layer. - `id` string, required — The ID to use when referring to this layer programmatically. - `name` string, required — The display name for the layer. - `summary` string, required — A one-sentence summary of the layer. You can see this summary when you browse a list of layers on the platform portal. - `description` string, required — A detailed description of the layer and what it contains. This information appears on the 'Overview' tab when you open a layer in the platform portal. - `coverage` Coverage — The geographic area that this layer covers - `adminAreas` string[] — A list of ISO 3166 two-letter codes for countries and regions optionally followed by up to three characters codes for subdivisions, such as 'DE', 'PL', or 'CN-HK'. - `schema` Schema — Describes a HRN for the layer schema. Can be updated by the user for any kind of layer. - `hrn` string - `contentType` string, required — The MIME type of the data is stored in this layer. Cannot be updated for `objectstore` and `interactivemap` layers. The default value for interactivemap layer is `application/geo+json` because the data is stored and retrieved in GeoJSON format compatible with RFC-7946 (https://www.rfc-editor.org/rfc/rfc7946). - `contentEncoding` 'gzip' — Identifies whether the data is compressed. Can be updated only for the stream layer. - `tags` string[], required — Some keywords that help to find the layer when searching in the platform portal - `billingTags` string[], required — List of billing tags a free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alphanumeric ASCII characters [A-Za-z0-9] and the following special characters: - _ (except first and last character). - `indexProperties` IndexProperties - `ttl` '7.days' | '15.days' | '1.month' | '2.months' | '3.months' | '4.months' | '6.months' | '1.year' | '1.5.years' | '2.year' | 'unlimited' — Amount of time data will remain in index layer. If not specified, it defaults to 7 days. - `indexDefinitions` IndexDefinition[] - `name` string - `type` 'bool' | 'int' | 'string' | 'heretile' | 'timewindow' - `duration` integer — The `timewindow` enum type represents the time slice (*not* just a point in time) and it denotes the finest time granularity at which the data will be indexed and later queried. The `timewindow` type has an attribute duration that represents the time slice length. It is *not* mutable. Both time key value and time type duration are expressed in milliseconds (time value is milliseconds since `Epoch`). Value of duration is between 10 minutes and 1 day in milliseconds. - `zoomLevel` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 — The `heretile` enum type represents the tile ID in the HERE tile map tiling scheme. The `heretile` type has an attribute `zoomLevel` that represents the size of the tile and is *not* mutable. - `digest` 'MD5' | 'SHA-1' | 'SHA-256' — The digest algorithm used to calculate the checksum for the partitions in this layer. If specified, you can assume that all partitions in the layer, at every version, were calculated using this algorithm. Note that it is the responsibility of the data publisher to use this algorithm to calculate partition checksums. The HERE platform services do not verify that the specified algorithm was actually used. - `crc` 'CRC-32C' — The CRC algorithm used to calculate the checksum for the partitions in this layers - `layerType` 'index', required — The type of data availability that this layer provides - CreateObjectstoreLayer — Describes properties of a catalog object store layer. - `id` string, required — The ID to use when referring to this layer programmatically. - `name` string, required — The display name for the layer. - `summary` string, required — A one-sentence summary of the layer. You can see this summary when you browse a list of layers on the platform portal. - `description` string, required — A detailed description of the layer and what it contains. This information appears on the 'Overview' tab when you open a layer in the platform portal. - `coverage` Coverage — The geographic area that this layer covers - `adminAreas` string[] — A list of ISO 3166 two-letter codes for countries and regions optionally followed by up to three characters codes for subdivisions, such as 'DE', 'PL', or 'CN-HK'. - `schema` Schema — Describes a HRN for the layer schema. Can be updated by the user for any kind of layer. - `hrn` string - `tags` string[], required — Some keywords that help to find the layer when searching in the platform portal - `billingTags` string[], required — List of billing tags a free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alphanumeric ASCII characters [A-Za-z0-9] and the following special characters: - _ (except first and last character). - `objectStoreProperties` ObjectStoreProperties - `encryptionType` 'hereEncryption' | 'cloudEncryption' — Defines type of encryption to apply for data at rest. 'hereEncryption' is default and ensures that encryption keys are managed by HERE, 'cloudEncryption' uses standard cloud providers encryption mechanism like AWS S3 Bucket keys or similar. - `ttl` '1.days' | '3.days' | '7.days' | '15.days' | '1.month' | '2.months' | '3.months' | '4.months' | '6.months' | '1.year' | '1.5.years' | '2.years' | '3.years' | '5.years' | 'unlimited' — Amount of time data will remain in objectstore layer. If not specified, it defaults to unlimited. - `layerType` 'objectstore', required — The type of data availability that this layer provides - CreateInteractiveMapsLayer — Describes properties of a catalog interactive maps layer. - `id` string, required — The ID to use when referring to this layer programmatically. - `name` string, required — The display name for the layer. - `summary` string, required — A one-sentence summary of the layer. You can see this summary when you browse a list of layers on the platform portal. - `description` string, required — A detailed description of the layer and what it contains. This information appears on the 'Overview' tab when you open a layer in the platform portal. - `schema` Schema — Describes a HRN for the layer schema. Can be updated by the user for any kind of layer. - `hrn` string - `tags` string[], required — Some keywords that help to find the layer when searching in the platform portal - `billingTags` string[], required — List of billing tags a free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alphanumeric ASCII characters [A-Za-z0-9] and the following special characters: - _ (except first and last character). - `interactiveMapProperties` InteractiveMapProperties - `searchableProperties` string[] — A list properties that must be indexed for faster queries. - `extends` Extends — Extension definition that allows a layer's content to be based on an existing layer. Entities in the extension layer override features with the same ID in the extended layer. - `catalogHrn` string, required — Catalog HRN of the layer being extended. - `layerId` string, required — Layer ID of the layer being extended. - `versionsToKeep` integer — Defines how many versions are kept, while older versions may be purged. This value is set to 1 by default, so that there is only one (HEAD) state of the layer and no further versions are kept. If the value is greater than 1, then older versions, up to the "versionsToKeep" version, can be retrieved, such as by ?version=. The value for versionsToKeep cannot be modified when set to 1. The value can be modified when set to a value greater than 1, but it cannot be changed to 1. The maximum value for versionsToKeep can be set to 1000000000. - `readOnly` boolean — This property can be used to make any interactive map layer read-only. The boolean value true or false defines if the layer is read-only or not. - `layerType` 'interactivemap', required — The type of data availability that this layer provides - `areaScheme` string — This field is deprecated on the catalog level. Use **/catalogs/{catalogHrn}/dataSubsets** to set areaScheme in the dataSubset instead. HERE Resource Name (HRN) of the Area Scheme used in the data subset. After deprecation setting areaScheme on the catalog level takes no effect. It will simply be ignored. - `subsetRestrictions` boolean — This field is deprecated on the catalog level. Use subsetRestrictions on the layer level only. Indicates if the subsetRestrictions for a layer is enabled or not. Supported only for layers with heretile partitioning. After deprecation setting subsetRestrictions on the catalog level takes no effect. It will simply be ignored. - `version` integer — The version of the catalog configuration. Every change in this number indicates change in catalog configuration. Examples of changes in catalog configuration include changing catalog parameters and adding layers. Note that the catalog configuration version is not the same as the metadata/data version. Configuration and metadata versions are independent of each other and indicate different kinds of changes. - `notifications` Notifications — When set to true, a notification is written to the notification stream each time the version of the catalog changes. This field is optional, but you can update the value to modify notifications. Additionally, this field is not removable, and a null value is not allowed. - `enabled` boolean - `replication` Replication - `regions` ReplicationRegion[] — A list of the catalog's replication regions and each region's role. For multi-region replication, catalogs list should contain multiple items where at least one should be with a `primary` role. For single-region replication, catalogs should define `primary` region. Both `eu-ireland` and `us-oregon` are allowed as primary region. - `id` 'eu-ireland' | 'us-oregon' | 'ap-seoul', required — The ID of the region - `role` 'primary' | 'secondary' — Indicates whether the region is a primary or failover region. You can specify one of the following: `primary` - The region is used by default for reading and writing. `secondary` - The region used as a failover region. - `automaticVersionDeletion` union - object - `numberOfVersionsToKeep` integer, required — Specifies how many versions to keep. To optimise storage costs, you can specify how many latest versions to keep. The minimum number of versions to keep is 1. The maximum number of versions to keep is 50,000. - `ttlDays` integer — Specifies the number of days to keep versions, counting from their creation time. The minimum ttlDays value is 3 days. - object - `numberOfVersionsToKeep` integer — Specifies how many versions to keep. To optimise storage costs, you can specify how many latest versions to keep. The minimum number of versions to keep is 1. The maximum number of versions to keep is 50,000. - `ttlDays` integer, required — Specifies the number of days to keep versions, counting from their creation time. The minimum ttlDays value is 3 days. ## Response `202` Accepted - your request was received and is being processed. - StatusLink — Describes the status and href of the create/update/delete resource such as a catalog. - `href` string — href of the created/update/delete catalog action - `configToken` string — token for getting the status of created/update/delete catalog action - `title` string — Title of the action - `type` string — Type of the href ## Other responses - `400` — Bad Request - indicates that your request failed fast validation, such as syntax or some logical errors. - `401` — Unauthorized - `402` — Payment required - indicates that your request failed because performing the catalog operation would exceed the resource limit. - `403` — Forbidden - `409` — Conflict - indicates that a catalog with the same catalog ID already exists or is in the process of being created. --- [API](https://skmtc.dev/here/apis/query-api-v1.md) · [All operations](https://skmtc.dev/here/apis/query-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/here/query-api-v1/revisions/30e5d2645407/schema)