DataSpecs Class

When requesting multiple sets of data for a particular location, it makes sense to use multiple DataSpec objects to retrieve as much data as possible in a single request. This is cheaper and faster than fetching the same data across multiple requests. For example, for a particular location you might want to request heating and cooling degree days at 5 different base temperatures each. This would require 10 different DataSpec objects in total. By putting all 10 DataSpec objects in a single DataSpecs object, you could fetch all 10 sets of data in a single request.

For most use cases, all you will ever need to do with this class is use the constructors to create instances to pass into LocationDataRequest objects. However, if you are customizing this framework (e.g. using it to construct requests but handling the response XML using your own system entirely), you will probably find it useful to understand about keys and the uniqueness of DataSpec objects.

Keys

The XML request (which this .NET framework generates internally) requires that each DataSpec be assigned a unique string key attribute so that its corresponding data set can be found in the XML response (which this .NET framework parses internally). This DataSpecs class is central to the way that the keys are created and managed. It essentially gives you two options for key management:

1. You can let this DataSpecs class generate and manage the keys entirely, such that you never have to see them or use them directly. This is the sensible option if you're sticking with the defaults and letting the .NET framework parse the XML response. With this option you do not need to deal with keys at all - you can fetch your data set objects out of the LocationDataResponse using the DataSpec objects that you created for the request (and kept on hand for this purpose).
2. You can specify your own keys explicitly. The only reason we can think of for doing this is if, for whatever reason, you are parsing or transforming the XML response yourself and your parsing/transforming code expects the keys to have specific values or a specific format (e.g. matching keys in a database of yours). If this is the case, use the DataSpecsCustomKeyBuilder class to create a DataSpecs object with your own custom key-to-DataSpec mappings.

Uniqueness of DataSpec objects

There is no point in submitting a request containing multiple identical DataSpec objects, as it would lead to unnecessary duplication in the results and unnecessary bandwidth usage for the communication between the client and API servers.

Unless you are specifying your own keys (using DataSpecsCustomKeyBuilder), this class is set up to prevent duplicate DataSpec objects from being submitted as part of a request. It does this by filtering and discarding all duplicate DataSpec objects passed in to the constructors of this class. So, if you pass 10 DataSpec objects to one of the constructors, and only 5 of those are unique, then only the 5 unique DataSpec objects will be stored internally and sent as part of the XML request.

Because discarded duplicate DataSpec objects are identical to their retained counterparts, you can still use the duplicates to retrieve fetched data out of the LocationDataResponse. In other words, the internal process of filtering and discarding duplicate DataSpec objects should not affect the way in which you use this API.

If you create your own keys using DataSpecsCustomKeyBuilder, then duplicate DataSpec objects are not filtered. Filtering duplicate DataSpec objects would also involve filtering the keys associated with the duplicates, and this could cause problems for code of yours that was expecting those keys in the XML response. You can rely on the fact that, if you define your own DataSpec keys using CustomKeyBuilder, your XML response will contain entries for all of your keys, irrespective of whether some of the data associated with those keys is duplicated.

Reference