Repository: datacommonsorg/api-python
Pull request #224: Add support for domain and facet filters
Author: login: jm-rivera
Created: 2025-03-20T14:17:46Z | Merged: 2025-03-20T20:09:17Z

This PR adds support for the domains and facets filters for the Observations endpoint. These filters were recently documented by @kmoscoe.

The filters are implemented as additional parameters for the `ObservationEndpoint`:
```python
domains_filter: Optional[str | list[str]] = None
facets_filter: Optional[str | list[str]] = None
```
They are used when building the payload via the `ObservationRequestPayload`. The payload will add a "filter" key with the right contents if either `domains_filter` or `facets_filter` is used.

From a user point of view, this PR will enable this type of queries

```python
from datacommons_client import DataCommonsClient

# Create a DataCommonsClient object
dc = DataCommonsClient(dc_instance="datacommons.one.org")

response_with_facet_filter = dc.observation.fetch(
    variable_dcids="Count_Person",
    entity_dcids="country/USA",
    date="latest",
    facets_filter="1145703171"
)

response_with_domain_filter = dc.observation.fetch(
    variable_dcids="Count_Person",
    entity_dcids="country/USA",
    date="latest",
    domains_filter="www2.census.gov"
)
```

The PR also modifies existing tests to correctly test cases where these two new filters are used.




Diff:
diff --git a/datacommons_client/client.py b/datacommons_client/client.py
index c26ae433..77d5ef39 100644
--- a/datacommons_client/client.py
+++ b/datacommons_client/client.py
@@ -99,13 +99,12 @@ def observations_dataframe(
 
     if entity_dcids == "all":
       observations = self.observation.fetch_observations_by_entity_type(
-          variable_dcids=variable_dcids,
           date=date,
-          entity_type=entity_type,
           parent_entity=parent_entity,
-      )
+          entity_type=entity_type,
+          variable_dcids=variable_dcids)
     else:
       observations = self.observation.fetch_observations_by_entity(
-          variable_dcids=variable_dcids, date=date, entity_dcids=entity_dcids)
+          date=date, entity_dcids=entity_dcids, variable_dcids=variable_dcids)
 
     return pd.DataFrame(observations.get_observations_as_records())
diff --git a/datacommons_client/endpoints/observation.py b/datacommons_client/endpoints/observation.py
index f0749109..1548a29a 100644
--- a/datacommons_client/endpoints/observation.py
+++ b/datacommons_client/endpoints/observation.py
@@ -28,6 +28,8 @@ def fetch(
       select: Optional[list[ObservationSelect | str]] = None,
       entity_dcids: Optional[str | list[str]] = None,
       entity_expression: Optional[str] = None,
+      filter_facet_domains: Optional[str | list[str]] = None,
+      filter_facet_ids: Optional[str | list[str]] = None,
   ) -> ObservationResponse:
     """
         Fetches data from the observation endpoint.
@@ -40,6 +42,8 @@ def fetch(
                 Defaults to ["date", "variable", "entity", "value"].
             entity_dcids (Optional[str | list[str]]): One or more entity IDs to filter the data.
             entity_expression (Optional[str]): A string expression to filter entities.
+            filter_facet_domains (Optional[str | list[str]]): One or more domain names to filter the data.
+            filter_facet_ids (Optional[str | list[str]]): One or more facet IDs to filter the data.
 
         Returns:
             ObservationResponse: The response object containing observations for the specified query.
@@ -51,6 +55,8 @@ def fetch(
         select=select,
         entity_dcids=entity_dcids,
         entity_expression=entity_expression,
+        filter_facet_domains=filter_facet_domains,
+        filter_facet_ids=filter_facet_ids,
     ).to_dict
 
     # Send the request
@@ -61,6 +67,9 @@ def fetch_latest_observations(
       variable_dcids: str | list[str],
       entity_dcids: Optional[str | list[str]] = None,
       entity_expression: Optional[str] = None,
+      *,
+      filter_facet_domains: Optional[str | list[str]] = None,
+      filter_facet_ids: Optional[str | list[str]] = None,
   ) -> ObservationResponse:
     """
         Fetches the latest observations for the given variable and entity.
@@ -69,6 +78,8 @@ def fetch_latest_observations(
             variable_dcids (str | list[str]): One or more variable IDs for the data.
             entity_dcids (Optional[str | list[str]]): One or more entity IDs to filter the data.
             entity_expression (Optional[str]): A string expression to filter entities.
+            filter_facet_domains: Optional[str | list[str]: One or more domain names to filter the data.
+            filter_facet_ids: Optional[str | list[str]: One or more facet IDs to filter the data.
 
         Returns:
             ObservationResponse: The response object containing observations for the specified query.
@@ -78,25 +89,35 @@ def fetch_latest_observations(
         date=ObservationDate.LATEST,
         entity_dcids=entity_dcids,
         entity_expression=entity_expression,
+        filter_facet_domains=filter_facet_domains,
+        filter_facet_ids=filter_facet_ids,
     )
 
   def fetch_latest_observations_by_entity(
       self,
       variable_dcids: str | list[str],
       entity_dcids: str | list[str],
+      *,
+      filter_facet_domains: Optional[str | list[str]] = None,
+      filter_facet_ids: Optional[str | list[str]] = None,
   ) -> ObservationResponse:
     """Fetches the latest observations for the given variable and entities.
 
         Args:
             variable_dcids (str | list[str]): One or more variable IDs for the data.
             entity_dcids (str | list[str]): One or more entity IDs to filter the data.
+            filter_facet_domains: Optional[str | list[str]: One or more domain names to filter the data.
+            filter_facet_ids: Optional[str | list[str]: One or more facet IDs to filter the data.
 
         Returns:
             ObservationResponse: The response object containing observations for the specified query.
         """
 
-    return self.fetch_latest_observations(variable_dcids=variable_dcids,
-                                          entity_dcids=entity_dcids)
+    return self.fetch_latest_observations(
+        variable_dcids=variable_dcids,
+        entity_dcids=entity_dcids,
+        filter_facet_domains=filter_facet_domains,
+        filter_facet_ids=filter_facet_ids)
 
   def fetch_observations_by_entity_type(
       self,
@@ -104,6 +125,9 @@ def fetch_observations_by_entity_type(
       parent_entity: str,
       entity_type: str,
       variable_dcids: str | list[str],
+      *,
+      filter_facet_domains: Optional[str | list[str]] = None,
+      filter_facet_ids: Optional[str | list[str]] = None,
   ) -> ObservationResponse:
     """
         Fetches all observations for a given entity type.
@@ -118,6 +142,8 @@ def fetch_observations_by_entity_type(
                 For example, "Country" or "Region".
             variable_dcids (str | list[str]): The variable(s) to fetch observations for.
                 This can be a single variable ID or a list of IDs.
+            filter_facet_domains: Optional[str | list[str]: One or more domain names to filter the data.
+            filter_facet_ids: Optional[str | list[str]: One or more facet IDs to filter the data.
 
         Returns:
             ObservationResponse: The response object containing observations for the specified entity type.
@@ -142,6 +168,8 @@ def fetch_observations_by_entity_type(
         select=[s for s in ObservationSelect],
         entity_expression=
         f"{parent_entity}<-containedInPlace+{{typeOf:{entity_type}}}",
+        filter_facet_domains=filter_facet_domains,
+        filter_facet_ids=filter_facet_ids,
     )
 
   def fetch_observations_by_entity(
@@ -149,6 +177,9 @@ def fetch_observations_by_entity(
       date: ObservationDate | str,
       entity_dcids: str | list[str],
       variable_dcids: str | list[str],
+      *,
+      filter_facet_domains: Optional[str | list[str]] = None,
+      filter_facet_ids: Optional[str | list[str]] = None,
   ) -> ObservationResponse:
     """
         Fetches all observations for a given entity type.
@@ -160,6 +191,8 @@ def fetch_observations_by_entity(
             entity_dcids (str | list[str]): One or more entity IDs to filter the data.
             variable_dcids (str | list[str]): The variable(s) to fetch observations for.
                 This can be a single variable ID or a list of IDs.
+            filter_facet_domains: Optional[str | list[str]: One or more domain names to filter the data.
+            filter_facet_ids: Optional[str | list[str]: One or more facet IDs to filter the data.
 
         Returns:
             ObservationResponse: The response object containing observations for the specified entity type.
@@ -180,6 +213,8 @@ def fetch_observations_by_entity(
     return self.fetch(
         variable_dcids=variable_dcids,
         date=date,
-        entity_dcids=entity_dcids,
         select=[s for s in ObservationSelect],
+        entity_dcids=entity_dcids,
+        filter_facet_domains=filter_facet_domains,
+        filter_facet_ids=filter_facet_ids,
     )
diff --git a/datacommons_client/endpoints/payloads.py b/datacommons_client/endpoints/payloads.py
index 0ea7547a..0b854b8d 100644
--- a/datacommons_client/endpoints/payloads.py
+++ b/datacommons_client/endpoints/payloads.py
@@ -104,6 +104,8 @@ class ObservationRequestPayload(EndpointRequestPayload):
             Defaults to ["date", "variable", "entity", "value"].
         entity_dcids (Optional[str | list[str]]): One or more entity IDs to filter the data.
         entity_expression (Optional[str]): A string expression to filter entities.
+        filter_facet_domains (Optional[str | list[str]]): One or more domain names to filter the data.
+        filter_facet_ids (Optional[str | list[str]]): One or more facet IDs to filter the data.
     """
 
   date: ObservationDate | str = ""
@@ -111,6 +113,8 @@ class ObservationRequestPayload(EndpointRequestPayload):
   select: Optional[list[ObservationSelect | str]] = None
   entity_dcids: Optional[str | list[str]] = None
   entity_expression: Optional[str] = None
+  filter_facet_domains: Optional[str | list[str]] = None
+  filter_facet_ids: Optional[str | list[str]] = None
 
   def __post_init__(self):
     """
@@ -135,7 +139,8 @@ def normalize(self):
     """
         Normalizes the payload for consistent internal representation.
 
-        - Converts `variable_dcids` and `entity_dcids` to lists if they are passed as strings.
+        - Converts `variable_dcids`, `entity_dcids`, `filter_facet_domains` and `filter_facet_ids`
+         to lists if they are passed as strings.
         - Normalizes the `date` field to ensure it is in the correct format.
         """
     # Normalize variable
@@ -152,6 +157,14 @@ def normalize(self):
     elif (self.date.upper() == "LATEST") or (self.date == ""):
       self.date = ObservationDate.LATEST
 
+    # Normalize filter_facet_domains
+    if isinstance(self.filter_facet_domains, str):
+      self.filter_facet_domains = [self.filter_facet_domains]
+
+    # Normalize filter_facet_ids
+    if isinstance(self.filter_facet_ids, str):
+      self.filter_facet_ids = [self.filter_facet_ids]
+
   def validate(self):
     """
         Validates the payload to ensure consistency and correctness.
@@ -184,7 +197,9 @@ def to_dict(self) -> dict:
         Returns:
             dict: The normalized and validated payload.
         """
-    return {
+
+    # Create the payload dictionary
+    payload = {
         "date": self.date,
         "variable": {
             "dcids": self.variable_dcids
@@ -197,6 +212,20 @@ def to_dict(self) -> dict:
         "select": self.select,
     }
 
+    # Create a filter dictionary with only non-empty values
+    filters = {
+        k: v for k, v in {
+            "domains": self.filter_facet_domains,
+            "facet_ids": self.filter_facet_ids,
+        }.items() if v
+    }
+
+    # Only add filter if it's not empty
+    if filters:
+      payload["filter"] = filters
+
+    return payload
+
 
 @dataclass
 class ResolveRequestPayload(EndpointRequestPayload):
diff --git a/datacommons_client/tests/endpoints/test_observation_endpoint.py b/datacommons_client/tests/endpoints/test_observation_endpoint.py
index 82bfdfd5..483f6675 100644
--- a/datacommons_client/tests/endpoints/test_observation_endpoint.py
+++ b/datacommons_client/tests/endpoints/test_observation_endpoint.py
@@ -11,12 +11,12 @@ def test_fetch():
   api_mock = MagicMock(spec=API)
   endpoint = ObservationEndpoint(api=api_mock)
 
-  response = endpoint.fetch(
-      variable_dcids="dcid/variableID",
-      date=ObservationDate.LATEST,
-      select=["date", "variable", "entity", "value"],
-      entity_dcids="dc/EntityID",
-  )
+  response = endpoint.fetch(variable_dcids="dcid/variableID",
+                            date=ObservationDate.LATEST,
+                            select=["date", "variable", "entity", "value"],
+                            entity_dcids="dc/EntityID",
+                            filter_facet_domains="domain1",
+                            filter_facet_ids="facet1")
 
   # Check the response
   assert isinstance(response, ObservationResponse)
@@ -31,6 +31,10 @@ def test_fetch():
           "dcids": ["dc/EntityID"],
       },
       "select": ["date", "variable", "entity", "value"],
+      "filter": {
+          "domains": ["domain1"],
+          "facet_ids": ["facet1"]
+      }
   },
                                         endpoint="observation",
                                         all_pages=True,
@@ -74,7 +78,7 @@ def test_fetch_latest_observations_by_entity():
   response = endpoint.fetch_latest_observations_by_entity(
       variable_dcids="dc/VariableID",
       entity_dcids=["dc/Entity1", "dc/Entity2"],
-  )
+      filter_facet_ids="facet1")
 
   # Check the response
   assert isinstance(response, ObservationResponse)
@@ -89,6 +93,9 @@ def test_fetch_latest_observations_by_entity():
           "dcids": ["dc/Entity1", "dc/Entity2"]
       },
       "select": ["date", "variable", "entity", "value"],
+      "filter": {
+          "facet_ids": ["facet1"]
+      }
   },
                                         endpoint="observation",
                                         all_pages=True,
@@ -104,8 +111,7 @@ def test_fetch_observations_by_entity_type():
       date="2023",
       parent_entity="Earth",
       entity_type="Country",
-      variable_dcids="dc/VariableID",
-  )
+      variable_dcids="dc/VariableID")
 
   # Check the response
   assert isinstance(response, ObservationResponse)
diff --git a/datacommons_client/tests/endpoints/test_payloads.py b/datacommons_client/tests/endpoints/test_payloads.py
index 616bfdf3..a6427b89 100644
--- a/datacommons_client/tests/endpoints/test_payloads.py
+++ b/datacommons_client/tests/endpoints/test_payloads.py
@@ -38,11 +38,20 @@ def test_observation_payload_normalize():
       variable_dcids="var1",
       select=["variable", "entity"],
       entity_dcids="ent1",
+      filter_facet_domains="domain1",
+      filter_facet_ids="facets1",
   )
   assert payload.variable_dcids == ["var1"]
   assert payload.entity_dcids == ["ent1"]
+  assert payload.filter_facet_domains == ["domain1"]
+  assert payload.filter_facet_ids == ["facets1"]
   assert payload.date == ObservationDate.LATEST
 
+  assert "filter" in payload.to_dict
+  assert "facet_ids" in payload.to_dict["filter"]
+  assert "domains" in payload.to_dict["filter"]
+
+  # Check that when domain and facets are not included, they are not in the payload
   payload = ObservationRequestPayload(
       date="all",
       variable_dcids=["var1"],
@@ -52,6 +61,7 @@ def test_observation_payload_normalize():
   assert payload.date == ObservationDate.ALL
   assert payload.variable_dcids == ["var1"]
   assert payload.entity_dcids == ["ent1"]
+  assert "filter" not in payload.to_dict
 
 
 def test_observation_select_invalid_value():
@@ -101,6 +111,7 @@ def test_observation_payload_to_dict():
       variable_dcids="var1",
       select=["variable", "entity"],
       entity_dcids="ent1",
+      filter_facet_ids="facets1",
   )
   assert payload.to_dict == {
       "date": ObservationDate.LATEST,
@@ -111,6 +122,9 @@ def test_observation_payload_to_dict():
           "dcids": ["ent1"]
       },
       "select": ["variable", "entity"],
+      "filter": {
+          "facet_ids": ["facets1"]
+      }
   }
 
 


Reviews:
user: login: dwnoble
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T16:57:54Z
user: login: jm-rivera
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T17:23:38Z
user: login: jm-rivera
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T17:27:08Z
user: login: dwnoble
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T18:03:42Z

Review comments:
diff_hunk: @@ -40,6 +41,8 @@ def fetch(
                 Defaults to ["date", "variable", "entity", "value"].
             entity_dcids (Optional[str | list[str]]): One or more entity IDs to filter the data.
             entity_expression (Optional[str]): A string expression to filter entities.
+            domains_filter (Optional[str | list[str]]): One or more domain names to filter the data.
path: datacommons_client/endpoints/observation.py
user: login: dwnoble
body: What do you think about naming these `filter_facet_domains` and `filter_facet_ids` so they line up more closely with the api/v2 arguments `filter.facet_domains` and `filter.facet_ids`?  That would also be similar to how we have the params `entity_dcids` and `entity_expression` mapping to the /v2/ arguments `entity.dcids` and `entity.expression`
created_at: 2025-03-20T16:57:42Z
author_association: CONTRIBUTOR
diff_hunk: @@ -40,6 +41,8 @@ def fetch(
                 Defaults to ["date", "variable", "entity", "value"].
             entity_dcids (Optional[str | list[str]]): One or more entity IDs to filter the data.
             entity_expression (Optional[str]): A string expression to filter entities.
+            domains_filter (Optional[str | list[str]]): One or more domain names to filter the data.
path: datacommons_client/endpoints/observation.py
user: login: jm-rivera
body: very good idea, will update now!
created_at: 2025-03-20T17:23:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -40,6 +41,8 @@ def fetch(
                 Defaults to ["date", "variable", "entity", "value"].
             entity_dcids (Optional[str | list[str]]): One or more entity IDs to filter the data.
             entity_expression (Optional[str]): A string expression to filter entities.
+            domains_filter (Optional[str | list[str]]): One or more domain names to filter the data.
path: datacommons_client/endpoints/observation.py
user: login: jm-rivera
body: Done [here](https://github.com/datacommonsorg/api-python/pull/224/commits/f5e99b7f3db0f6169bb0612024f41c8930a1e211)  and [here](https://github.com/datacommonsorg/api-python/pull/224/commits/59aafd8102671bd9b6fa42a58a6f087d8641aa60)
created_at: 2025-03-20T17:27:07Z
author_association: CONTRIBUTOR

PR comments:
user: login: jm-rivera
created_at: 2025-03-20T15:28:38Z
body: @kmoscoe while researching this, I came across this: https://github.com/datacommonsorg/website/blob/master/server/services/datacommons.py#L192-L209

[The docs](https://docs.datacommons.org/api/rest/v2/observation) don't mention it but it looks like one of the possible 'select' fields is 'facet'. It would be very handed to have that documented, if possible.

It's not necessary for this PR, but currently users have no way of getting facet ids from anywhere... and it looks like that 'select' option could be the way (at least that's how the website gets the facet ids). 

Maybe @dwnoble can tell us more about how they use that info?
author_association: CONTRIBUTOR
user: login: kmoscoe
created_at: 2025-03-20T15:42:24Z
body: I'm a bit confused -- facets and their IDs are always returned with select
= date, value.  e.g.:

 "facets": {
    ...
    "2176550201" : {
      "importName" : "USCensusPEP_Annual_Population",
      "measurementMethod" : "CensusPEPSurvey",
      "observationPeriod" : "P1Y",
      "provenanceUrl" : "https://www2.census.gov/programs-surveys/popest/tables"
    },
    ...
   "2645850372" : {
         "importName" : "CensusACS5YearSurvey_AggCountry",
         "isDcAggregate" : true,
         "measurementMethod" : "CensusACS5yrSurvey",
         "provenanceUrl" : "https://www.census.gov/"
      },
    ...


What am I missing?

On Thu, Mar 20, 2025 at 8:29 AM Jorge Rivera ***@***.***>
wrote:

> @kmoscoe <https://github.com/kmoscoe> while researching this, I came
> across this:
> https://github.com/datacommonsorg/website/blob/master/server/services/datacommons.py#L192-L209
>
> The docs <https://docs.datacommons.org/api/rest/v2/observation> don't
> mention it but it looks like one of the possible 'select' fields is
> 'facet'. It would be very handed to have that documented, if possible.
>
> It's not necessary for this PR, but currently users have no way of getting
> facet ids from anywhere... and it looks like that 'select' option could be
> the way (at least that's how the website gets the facet ids).
>
> Maybe @dwnoble <https://github.com/dwnoble> can tell us more about how
> they use that info?
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2740854491>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UANCSMPBTOSSMGBKXL2VLNDZAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBQHA2TINBZGE>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
> [image: jm-rivera]*jm-rivera* left a comment
> (datacommonsorg/api-python#224)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2740854491>
>
> @kmoscoe <https://github.com/kmoscoe> while researching this, I came
> across this:
> https://github.com/datacommonsorg/website/blob/master/server/services/datacommons.py#L192-L209
>
> The docs <https://docs.datacommons.org/api/rest/v2/observation> don't
> mention it but it looks like one of the possible 'select' fields is
> 'facet'. It would be very handed to have that documented, if possible.
>
> It's not necessary for this PR, but currently users have no way of getting
> facet ids from anywhere... and it looks like that 'select' option could be
> the way (at least that's how the website gets the facet ids).
>
> Maybe @dwnoble <https://github.com/dwnoble> can tell us more about how
> they use that info?
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2740854491>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UANCSMPBTOSSMGBKXL2VLNDZAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBQHA2TINBZGE>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>

author_association: CONTRIBUTOR
user: login: jm-rivera
created_at: 2025-03-20T15:46:24Z
body: @kmoscoe I meant the payload rather than the response. So basically that 'facets' is not mentioned here:
<img width="1068" alt="image" src="https://github.com/user-attachments/assets/22a96b7e-9a29-4ccb-97d0-07620427214e" />

author_association: CONTRIBUTOR
user: login: kmoscoe
created_at: 2025-03-20T16:09:52Z
body: I understand, but it's always returned in the response. You mean I should
explicitly mention in it in the description of the select options?

You mean something like:

select
Required string literal select=variable and select=entity are required. If
specifed without select=date and select=value, no observations or facets are
returned. You can use this to first check the existence of variable-entity
pairs in the data and fetch all the variables that have data for given
entities.
select
Optional string literal If used, you must specify both select=date and
select=value. Returns actual observations, with the date and value for each
variable and entity queried, as well as facets and provenance data.

On Thu, Mar 20, 2025 at 8:46 AM Jorge Rivera ***@***.***>
wrote:

> @kmoscoe <https://github.com/kmoscoe> I meant the payload rather than the
> response. So basically that 'facets' is not mentioned here:
> image.png (view on web)
> <https://github.com/user-attachments/assets/22a96b7e-9a29-4ccb-97d0-07620427214e>
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2740910103>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UG7HYUHTE34AGWUTED2VLPGPAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBQHEYTAMJQGM>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
> [image: jm-rivera]*jm-rivera* left a comment
> (datacommonsorg/api-python#224)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2740910103>
>
> @kmoscoe <https://github.com/kmoscoe> I meant the payload rather than the
> response. So basically that 'facets' is not mentioned here:
> image.png (view on web)
> <https://github.com/user-attachments/assets/22a96b7e-9a29-4ccb-97d0-07620427214e>
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2740910103>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UG7HYUHTE34AGWUTED2VLPGPAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBQHEYTAMJQGM>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>

author_association: CONTRIBUTOR
user: login: jm-rivera
created_at: 2025-03-20T16:21:45Z
body: It's actually more similar to the variable-entity checks.

Basically if you request variable, entity, and facet (but not value and date), you can check that the variable and entity pair exists and you can get facet info (like sources, mesurementMethods, units, etc).

That can be useful if you want to then construct at request where you leverage the facet filter (implemented in this PR), as you could identify the facet that you want, before making the potentially much more expensive call to get the actual observations (by including value and date in `select`)
author_association: CONTRIBUTOR
user: login: kmoscoe
created_at: 2025-03-20T16:28:57Z
body: Ah, I see what you mean!  So IOW, the combination of
select=entity,variable,facet. Great point, will add this!

On Thu, Mar 20, 2025 at 9:22 AM Jorge Rivera ***@***.***>
wrote:

> It's actually more similar to the variable-entity checks.
>
> Basically if you request variable, entity, and facet (but not value and
> date), you can check that the variable and entity pair exists and you can
> get facet info (like sources, mesurementMethods, units, etc).
>
> That can be useful if you want to then construct at request where you
> leverage the facet filter (implemented in this PR), as you could identify
> the facet that you want, before making the potentially much more expensive
> call to get the actual observations (by including value and date in select
> )
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741017433>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UHICMJFHPC4KU6I2KD2VLTLBAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGAYTONBTGM>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
> [image: jm-rivera]*jm-rivera* left a comment
> (datacommonsorg/api-python#224)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741017433>
>
> It's actually more similar to the variable-entity checks.
>
> Basically if you request variable, entity, and facet (but not value and
> date), you can check that the variable and entity pair exists and you can
> get facet info (like sources, mesurementMethods, units, etc).
>
> That can be useful if you want to then construct at request where you
> leverage the facet filter (implemented in this PR), as you could identify
> the facet that you want, before making the potentially much more expensive
> call to get the actual observations (by including value and date in select
> )
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741017433>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UHICMJFHPC4KU6I2KD2VLTLBAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGAYTONBTGM>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>

author_association: CONTRIBUTOR
user: login: kmoscoe
created_at: 2025-03-20T16:36:29Z
body: Guess what? Just tried it, and it doesn't work. :-)  If you specify
select=variable,entity,facet, it's identical to to
select=variable,entity,date,value. 🤣 You get the full observations data.

On Thu, Mar 20, 2025 at 9:28 AM Kara Moscoe ***@***.***> wrote:

> Ah, I see what you mean!  So IOW, the combination of
> select=entity,variable,facet. Great point, will add this!
>
> On Thu, Mar 20, 2025 at 9:22 AM Jorge Rivera ***@***.***>
> wrote:
>
>> It's actually more similar to the variable-entity checks.
>>
>> Basically if you request variable, entity, and facet (but not value and
>> date), you can check that the variable and entity pair exists and you can
>> get facet info (like sources, mesurementMethods, units, etc).
>>
>> That can be useful if you want to then construct at request where you
>> leverage the facet filter (implemented in this PR), as you could identify
>> the facet that you want, before making the potentially much more expensive
>> call to get the actual observations (by including value and date in
>> select)
>>
>> —
>> Reply to this email directly, view it on GitHub
>> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741017433>,
>> or unsubscribe
>> <https://github.com/notifications/unsubscribe-auth/BHMM7UHICMJFHPC4KU6I2KD2VLTLBAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGAYTONBTGM>
>> .
>> You are receiving this because you were mentioned.Message ID:
>> ***@***.***>
>> [image: jm-rivera]*jm-rivera* left a comment
>> (datacommonsorg/api-python#224)
>> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741017433>
>>
>> It's actually more similar to the variable-entity checks.
>>
>> Basically if you request variable, entity, and facet (but not value and
>> date), you can check that the variable and entity pair exists and you can
>> get facet info (like sources, mesurementMethods, units, etc).
>>
>> That can be useful if you want to then construct at request where you
>> leverage the facet filter (implemented in this PR), as you could identify
>> the facet that you want, before making the potentially much more expensive
>> call to get the actual observations (by including value and date in
>> select)
>>
>> —
>> Reply to this email directly, view it on GitHub
>> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741017433>,
>> or unsubscribe
>> <https://github.com/notifications/unsubscribe-auth/BHMM7UHICMJFHPC4KU6I2KD2VLTLBAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGAYTONBTGM>
>> .
>> You are receiving this because you were mentioned.Message ID:
>> ***@***.***>
>>
>

author_association: CONTRIBUTOR
user: login: jm-rivera
created_at: 2025-03-20T16:41:24Z
body: I've tried it and then i see the length of the response. 

```python
data = dc.observation.fetch(
    variable_dcids=[
        "LifeExpectancy_Person_Female",
        "worldBank/SH_DTH_COMM_ZS"
    ],
    entity_dcids=["country/TGO"],
    date="all",
    select=["variable", "entity", "value", "date"],
)

print(len(data.to_json()))
```
Would be 10924 characters long

But (and this won't work in your version yet)

```python
data = dc.observation.fetch(
    variable_dcids=[
        "LifeExpectancy_Person_Female",
        "worldBank/SH_DTH_COMM_ZS"
    ],
    entity_dcids=["country/TGO"],
    date="all",
    select=["variable", "entity", "facet"],
)

print(len(data.to_json()))
```
Would be 2404 characters long.

The difference is the actual observations data, which are not included in the latter.


author_association: CONTRIBUTOR
user: login: dwnoble
created_at: 2025-03-20T16:52:08Z
body: Good find @jm-rivera - i didn't realize we hadn't documented this.

We use this functionality in the visualization tools facet selector to let users pick what data source/facet to show. It's also used as way to do a data 'existence check' in the natural language search endpoint to check if data exists without actually fetching it.

Kara: here are some working curl examples that fetch facets only and facets + observations for datacommons.one.org:

```
# Fetch facets only, no observations are returned
curl --request POST \
--url https://datacommons.one.org/core/api/v2/observation \
--data '{
  "select": ["variable", "entity", "facet"],
  "entity": {
      "dcids": ["country/NER"]
  },
  "variable": {
      "dcids": ["climateFinanceReceivedCommitments"]
  }
}'
```

```
# Fetch observation values, which also includes the facets
curl --request POST \
--url https://datacommons.one.org/core/api/v2/observation \
--data '{
  "select": ["variable", "entity", "date", "value"],
  "entity": {
      "dcids": ["country/NER"]
  },
  "variable": {
      "dcids": ["climateFinanceReceivedCommitments"]
  }
}'
```

author_association: CONTRIBUTOR
user: login: kmoscoe
created_at: 2025-03-20T17:05:07Z
body: Er, honestly I don't see any difference between them. The only difference I
could find is that the one with only "facet" omitted entities with no
results, while the other includes them with empty brackets.

On Thu, Mar 20, 2025 at 9:52 AM Dan Noble ***@***.***> wrote:

> Good find @jm-rivera <https://github.com/jm-rivera> - i didn't realize we
> hadn't documented this.
>
> We use this functionality in the visualization tools facet selector to let
> users pick what data source/facet to show. It's also used as way to do a
> data 'existence check' in the natural language search endpoint to check if
> data exists without actually fetching it.
>
> Kara: here are some working curl examples that fetch facets only and
> facets + observations for datacommons.one.org:
>
> # Fetch facets only, no observations are returned
> curl --request POST \
> --url https://datacommons.one.org/core/api/v2/observation \
> --data '{
>   "select": ["variable", "entity", "facet"],
>   "entity": {
>       "dcids": ["country/NER"]
>   },
>   "variable": {
>       "dcids": ["climateFinanceReceivedCommitments"]
>   }
> }'
>
> # Fetch observation values, which also includes the facets
> curl --request POST \
> --url https://datacommons.one.org/core/api/v2/observation \
> --data '{
>   "select": ["variable", "entity", "date", "value"],
>   "entity": {
>       "dcids": ["country/NER"]
>   },
>   "variable": {
>       "dcids": ["climateFinanceReceivedCommitments"]
>   }
> }'
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
> [image: dwnoble]*dwnoble* left a comment (datacommonsorg/api-python#224)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>
>
> Good find @jm-rivera <https://github.com/jm-rivera> - i didn't realize we
> hadn't documented this.
>
> We use this functionality in the visualization tools facet selector to let
> users pick what data source/facet to show. It's also used as way to do a
> data 'existence check' in the natural language search endpoint to check if
> data exists without actually fetching it.
>
> Kara: here are some working curl examples that fetch facets only and
> facets + observations for datacommons.one.org:
>
> # Fetch facets only, no observations are returned
> curl --request POST \
> --url https://datacommons.one.org/core/api/v2/observation \
> --data '{
>   "select": ["variable", "entity", "facet"],
>   "entity": {
>       "dcids": ["country/NER"]
>   },
>   "variable": {
>       "dcids": ["climateFinanceReceivedCommitments"]
>   }
> }'
>
> # Fetch observation values, which also includes the facets
> curl --request POST \
> --url https://datacommons.one.org/core/api/v2/observation \
> --data '{
>   "select": ["variable", "entity", "date", "value"],
>   "entity": {
>       "dcids": ["country/NER"]
>   },
>   "variable": {
>       "dcids": ["climateFinanceReceivedCommitments"]
>   }
> }'
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>

author_association: CONTRIBUTOR
user: login: kmoscoe
created_at: 2025-03-20T17:09:37Z
body: OMG, I see the difference: POST requests behave as you say, but GET
requests do not!!  Here's my test cases (key redacted):

 curl --request GET --url '
https://api.datacommons.org/v2/observation?key=...&date=LATEST&variable.dcids=Count_Person_Female&variable.dcids=Count_Person_Male&entity.dcids=country/CAN&entity.dcids=country/MEX&entity.dcids=country/SGP&entity.dcids=country/MYS&select=entity&select=variable&select=facet
'

{"byVariable":{"Count_Person_Female":{"byEntity":{"country/CAN":{"orderedFacets":[{"facetId":"4181918134","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1151455814","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1216205004","obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"4181918134","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"1151455814","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"3614729857","obsCount":6,"earliestDate":"1990","latestDate":"2020"}]}}},"Count_Person_Male":{"byEntity":{"country/CAN":{"orderedFacets":[{"facetId":"4181918134","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1151455814","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1216205004","obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"4181918134","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"1151455814","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"3614729857","obsCount":6,"earliestDate":"1990","latestDate":"2020"}]}}}},"facets":{"4181918134":{"importName":"OECDRegionalDemography_Population","provenanceUrl":"
https://data-explorer.oecd.org/vis?fs[0]=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df[ds]=dsDisseminateFinalDMZ&df[id]=DSD_REG_DEMO%40DF_POP_5Y&df[ag]=OECD.CFE.EDS&df[vs]=2.0&dq=A.......&to[TIME_PERIOD]=false&vw=tb&pd=%2C
","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1151455814":{"importName":"OECDRegionalDemography","provenanceUrl":"
https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR#
","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1216205004":{"importName":"CanadaStatistics","provenanceUrl":"
https://www150.statcan.gc.ca/n1/en/type/data?MM=1
"},"3251078590":{"importName":"MexicoCensus_AA2","provenanceUrl":"
https://data.humdata.org/dataset/cod-ps-mex
"},"3614729857":{"importName":"MexicoCensus","provenanceUrl":"
https://www.inegi.org.mx/temas/"}}}

$ curl --request GET --url '
https://api.datacommons.org/v2/observation?key=...&date=LATEST&variable.dcids=Count_Person_Female&variable.dcids=Count_Person_Male&entity.dcids=country/CAN&entity.dcids=country/MEX&entity.dcids=country/SGP&entity.dcids=country/MYS&select=entity&select=variable&select=date&select=value
'

{"byVariable":{"Count_Person_Female":{"byEntity":{"country/SGP":{},"country/MYS":{},"country/CAN":{"orderedFacets":[{"facetId":"1151455814","observations":[{"date":"2023","value":20084054}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"4181918134","observations":[{"date":"2023","value":20084054}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"1216205004","observations":[{"date":"2021","value":15839460}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","observations":[{"date":"2021","value":65833180}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"1151455814","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"4181918134","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"3614729857","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"}]}}},"Count_Person_Male":{"byEntity":{"country/MYS":{},"country/CAN":{"orderedFacets":[{"facetId":"1151455814","observations":[{"date":"2023","value":20013707}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"4181918134","observations":[{"date":"2023","value":20013707}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"1216205004","observations":[{"date":"2021","value":15139730}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","observations":[{"date":"2021","value":63139259}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"1151455814","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"4181918134","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"3614729857","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"}]},"country/SGP":{}}}},"facets":{"1151455814":{"importName":"OECDRegionalDemography","provenanceUrl":"
https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR#
","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"4181918134":{"importName":"OECDRegionalDemography_Population","provenanceUrl":"
https://data-explorer.oecd.org/vis?fs[0]=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df[ds]=dsDisseminateFinalDMZ&df[id]=DSD_REG_DEMO%40DF_POP_5Y&df[ag]=OECD.CFE.EDS&df[vs]=2.0&dq=A.......&to[TIME_PERIOD]=false&vw=tb&pd=%2C
","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1216205004":{"importName":"CanadaStatistics","provenanceUrl":"
https://www150.statcan.gc.ca/n1/en/type/data?MM=1
"},"3251078590":{"importName":"MexicoCensus_AA2","provenanceUrl":"
https://data.humdata.org/dataset/cod-ps-mex
"},"3614729857":{"importName":"MexicoCensus","provenanceUrl":"
https://www.inegi.org.mx/temas/"}}}

On Thu, Mar 20, 2025 at 10:04 AM Kara Moscoe ***@***.***> wrote:

> Er, honestly I don't see any difference between them. The only difference
> I could find is that the one with only "facet" omitted entities with no
> results, while the other includes them with empty brackets.
>
> On Thu, Mar 20, 2025 at 9:52 AM Dan Noble ***@***.***>
> wrote:
>
>> Good find @jm-rivera <https://github.com/jm-rivera> - i didn't realize
>> we hadn't documented this.
>>
>> We use this functionality in the visualization tools facet selector to
>> let users pick what data source/facet to show. It's also used as way to do
>> a data 'existence check' in the natural language search endpoint to check
>> if data exists without actually fetching it.
>>
>> Kara: here are some working curl examples that fetch facets only and
>> facets + observations for datacommons.one.org:
>>
>> # Fetch facets only, no observations are returned
>> curl --request POST \
>> --url https://datacommons.one.org/core/api/v2/observation \
>> --data '{
>>   "select": ["variable", "entity", "facet"],
>>   "entity": {
>>       "dcids": ["country/NER"]
>>   },
>>   "variable": {
>>       "dcids": ["climateFinanceReceivedCommitments"]
>>   }
>> }'
>>
>> # Fetch observation values, which also includes the facets
>> curl --request POST \
>> --url https://datacommons.one.org/core/api/v2/observation \
>> --data '{
>>   "select": ["variable", "entity", "date", "value"],
>>   "entity": {
>>       "dcids": ["country/NER"]
>>   },
>>   "variable": {
>>       "dcids": ["climateFinanceReceivedCommitments"]
>>   }
>> }'
>>
>> —
>> Reply to this email directly, view it on GitHub
>> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>,
>> or unsubscribe
>> <https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM>
>> .
>> You are receiving this because you were mentioned.Message ID:
>> ***@***.***>
>> [image: dwnoble]*dwnoble* left a comment (datacommonsorg/api-python#224)
>> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>
>>
>> Good find @jm-rivera <https://github.com/jm-rivera> - i didn't realize
>> we hadn't documented this.
>>
>> We use this functionality in the visualization tools facet selector to
>> let users pick what data source/facet to show. It's also used as way to do
>> a data 'existence check' in the natural language search endpoint to check
>> if data exists without actually fetching it.
>>
>> Kara: here are some working curl examples that fetch facets only and
>> facets + observations for datacommons.one.org:
>>
>> # Fetch facets only, no observations are returned
>> curl --request POST \
>> --url https://datacommons.one.org/core/api/v2/observation \
>> --data '{
>>   "select": ["variable", "entity", "facet"],
>>   "entity": {
>>       "dcids": ["country/NER"]
>>   },
>>   "variable": {
>>       "dcids": ["climateFinanceReceivedCommitments"]
>>   }
>> }'
>>
>> # Fetch observation values, which also includes the facets
>> curl --request POST \
>> --url https://datacommons.one.org/core/api/v2/observation \
>> --data '{
>>   "select": ["variable", "entity", "date", "value"],
>>   "entity": {
>>       "dcids": ["country/NER"]
>>   },
>>   "variable": {
>>       "dcids": ["climateFinanceReceivedCommitments"]
>>   }
>> }'
>>
>> —
>> Reply to this email directly, view it on GitHub
>> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>,
>> or unsubscribe
>> <https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM>
>> .
>> You are receiving this because you were mentioned.Message ID:
>> ***@***.***>
>>
>

author_association: CONTRIBUTOR
user: login: dwnoble
created_at: 2025-03-20T18:03:06Z
body: > OMG, I see the difference: POST requests behave as you say, but GET requests do not!! Here's my test cases (key redacted): curl --request GET --url ' https://api.datacommons.org/v2/observation?key=...&date=LATEST&variable.dcids=Count_Person_Female&variable.dcids=Count_Person_Male&entity.dcids=country/CAN&entity.dcids=country/MEX&entity.dcids=country/SGP&entity.dcids=country/MYS&select=entity&select=variable&select=facet ' {"byVariable":{"Count_Person_Female":{"byEntity":{"country/CAN":{"orderedFacets":[{"facetId":"4181918134","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1151455814","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1216205004","obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"4181918134","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"1151455814","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"3614729857","obsCount":6,"earliestDate":"1990","latestDate":"2020"}]}}},"Count_Person_Male":{"byEntity":{"country/CAN":{"orderedFacets":[{"facetId":"4181918134","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1151455814","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1216205004","obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"4181918134","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"1151455814","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"3614729857","obsCount":6,"earliestDate":"1990","latestDate":"2020"}]}}}},"facets":{"4181918134":{"importName":"OECDRegionalDemography_Population","provenanceUrl":" https://data-explorer.oecd.org/vis?fs[0]=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df[ds]=dsDisseminateFinalDMZ&df[id]=DSD_REG_DEMO%40DF_POP_5Y&df[ag]=OECD.CFE.EDS&df[vs]=2.0&dq=A.......&to[TIME_PERIOD]=false&vw=tb&pd=%2C ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1151455814":{"importName":"OECDRegionalDemography","provenanceUrl":" https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR# ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1216205004":{"importName":"CanadaStatistics","provenanceUrl":" https://www150.statcan.gc.ca/n1/en/type/data?MM=1 "},"3251078590":{"importName":"MexicoCensus_AA2","provenanceUrl":" https://data.humdata.org/dataset/cod-ps-mex "},"3614729857":{"importName":"MexicoCensus","provenanceUrl":" https://www.inegi.org.mx/temas/"}}} $ curl --request GET --url ' https://api.datacommons.org/v2/observation?key=...&date=LATEST&variable.dcids=Count_Person_Female&variable.dcids=Count_Person_Male&entity.dcids=country/CAN&entity.dcids=country/MEX&entity.dcids=country/SGP&entity.dcids=country/MYS&select=entity&select=variable&select=date&select=value ' {"byVariable":{"Count_Person_Female":{"byEntity":{"country/SGP":{},"country/MYS":{},"country/CAN":{"orderedFacets":[{"facetId":"1151455814","observations":[{"date":"2023","value":20084054}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"4181918134","observations":[{"date":"2023","value":20084054}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"1216205004","observations":[{"date":"2021","value":15839460}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","observations":[{"date":"2021","value":65833180}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"1151455814","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"4181918134","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"3614729857","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"}]}}},"Count_Person_Male":{"byEntity":{"country/MYS":{},"country/CAN":{"orderedFacets":[{"facetId":"1151455814","observations":[{"date":"2023","value":20013707}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"4181918134","observations":[{"date":"2023","value":20013707}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"1216205004","observations":[{"date":"2021","value":15139730}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","observations":[{"date":"2021","value":63139259}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"1151455814","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"4181918134","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"3614729857","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"}]},"country/SGP":{}}}},"facets":{"1151455814":{"importName":"OECDRegionalDemography","provenanceUrl":" https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR# ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"4181918134":{"importName":"OECDRegionalDemography_Population","provenanceUrl":" https://data-explorer.oecd.org/vis?fs[0]=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df[ds]=dsDisseminateFinalDMZ&df[id]=DSD_REG_DEMO%40DF_POP_5Y&df[ag]=OECD.CFE.EDS&df[vs]=2.0&dq=A.......&to[TIME_PERIOD]=false&vw=tb&pd=%2C ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1216205004":{"importName":"CanadaStatistics","provenanceUrl":" https://www150.statcan.gc.ca/n1/en/type/data?MM=1 "},"3251078590":{"importName":"MexicoCensus_AA2","provenanceUrl":" https://data.humdata.org/dataset/cod-ps-mex "},"3614729857":{"importName":"MexicoCensus","provenanceUrl":" https://www.inegi.org.mx/temas/"}}}
> […](#)
> On Thu, Mar 20, 2025 at 10:04 AM Kara Moscoe ***@***.***> wrote: Er, honestly I don't see any difference between them. The only difference I could find is that the one with only "facet" omitted entities with no results, while the other includes them with empty brackets. On Thu, Mar 20, 2025 at 9:52 AM Dan Noble ***@***.***> wrote: > Good find @jm-rivera <https://github.com/jm-rivera> - i didn't realize > we hadn't documented this. > > We use this functionality in the visualization tools facet selector to > let users pick what data source/facet to show. It's also used as way to do > a data 'existence check' in the natural language search endpoint to check > if data exists without actually fetching it. > > Kara: here are some working curl examples that fetch facets only and > facets + observations for datacommons.one.org: > > # Fetch facets only, no observations are returned > curl --request POST \ > --url https://datacommons.one.org/core/api/v2/observation \ > --data '{ > "select": ["variable", "entity", "facet"], > "entity": { > "dcids": ["country/NER"] > }, > "variable": { > "dcids": ["climateFinanceReceivedCommitments"] > } > }' > > # Fetch observation values, which also includes the facets > curl --request POST \ > --url https://datacommons.one.org/core/api/v2/observation \ > --data '{ > "select": ["variable", "entity", "date", "value"], > "entity": { > "dcids": ["country/NER"] > }, > "variable": { > "dcids": ["climateFinanceReceivedCommitments"] > } > }' > > — > Reply to this email directly, view it on GitHub > <[#224 (comment)](https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> > [image: dwnoble]*dwnoble* left a comment ([datacommonsorg/api-python#224](https://github.com/datacommonsorg/api-python/pull/224)) > <[#224 (comment)](https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333)> > > Good find @jm-rivera <https://github.com/jm-rivera> - i didn't realize > we hadn't documented this. > > We use this functionality in the visualization tools facet selector to > let users pick what data source/facet to show. It's also used as way to do > a data 'existence check' in the natural language search endpoint to check > if data exists without actually fetching it. > > Kara: here are some working curl examples that fetch facets only and > facets + observations for datacommons.one.org: > > # Fetch facets only, no observations are returned > curl --request POST \ > --url https://datacommons.one.org/core/api/v2/observation \ > --data '{ > "select": ["variable", "entity", "facet"], > "entity": { > "dcids": ["country/NER"] > }, > "variable": { > "dcids": ["climateFinanceReceivedCommitments"] > } > }' > > # Fetch observation values, which also includes the facets > curl --request POST \ > --url https://datacommons.one.org/core/api/v2/observation \ > --data '{ > "select": ["variable", "entity", "date", "value"], > "entity": { > "dcids": ["country/NER"] > }, > "variable": { > "dcids": ["climateFinanceReceivedCommitments"] > } > }' > > — > Reply to this email directly, view it on GitHub > <[#224 (comment)](https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

This example looks like it's working to me -- the first request returns only facets for each requested entity, and the second returns the facets + latest observation for each requested entity 
author_association: CONTRIBUTOR
user: login: kmoscoe
created_at: 2025-03-20T21:57:41Z
body: Oops, you are right, thanks for catching that!  (I somehow missed it. Sigh,
I forgot to pipe to json_pp so I could properly see the output. I got mixed
up by seeing 'obs' in the facets.)

OK, so now that I've thoroughly wasted your time, I will prepare a PR for
you to review.

Thank you for helping with this.

K

On Thu, Mar 20, 2025 at 11:03 AM Dan Noble ***@***.***> wrote:

> OMG, I see the difference: POST requests behave as you say, but GET
> requests do not!! Here's my test cases (key redacted): curl --request GET
> --url '
> https://api.datacommons.org/v2/observation?key=...&date=LATEST&variable.dcids=Count_Person_Female&variable.dcids=Count_Person_Male&entity.dcids=country/CAN&entity.dcids=country/MEX&entity.dcids=country/SGP&entity.dcids=country/MYS&select=entity&select=variable&select=facet
> '
> {"byVariable":{"Count_Person_Female":{"byEntity":{"country/CAN":{"orderedFacets":[{"facetId":"4181918134","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1151455814","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1216205004","obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"4181918134","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"1151455814","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"3614729857","obsCount":6,"earliestDate":"1990","latestDate":"2020"}]}}},"Count_Person_Male":{"byEntity":{"country/CAN":{"orderedFacets":[{"facetId":"4181918134","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1151455814","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1216205004","obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"4181918134","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"1151455814","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"3614729857","obsCount":6,"earliestDate":"1990","latestDate":"2020"}]}}}},"facets":{"4181918134":{"importName":"OECDRegionalDemography_Population","provenanceUrl":"
>
> https://data-explorer.oecd.org/vis?fs[0]=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df[ds]=dsDisseminateFinalDMZ&df[id]=DSD_REG_DEMO%40DF_POP_5Y&df[ag]=OECD.CFE.EDS&df[vs]=2.0&dq=A.......&to[TIME_PERIOD]=false&vw=tb&pd=%2C
> <https://data-explorer.oecd.org/vis?fs%5B0%5D=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df%5Bds%5D=dsDisseminateFinalDMZ&df%5Bid%5D=DSD_REG_DEMO%40DF_POP_5Y&df%5Bag%5D=OECD.CFE.EDS&df%5Bvs%5D=2.0&dq=A.......&to%5BTIME_PERIOD%5D=false&vw=tb&pd=%2C>
> ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1151455814":{"importName":"OECDRegionalDemography","provenanceUrl":"
> https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR#
> ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1216205004":{"importName":"CanadaStatistics","provenanceUrl":"
> https://www150.statcan.gc.ca/n1/en/type/data?MM=1
> "},"3251078590":{"importName":"MexicoCensus_AA2","provenanceUrl":"
> https://data.humdata.org/dataset/cod-ps-mex "},"3614729857
> <(361)%20472-9857>":{"importName":"MexicoCensus","provenanceUrl":"
> https://www.inegi.org.mx/temas/"}}} $ curl --request GET --url '
> https://api.datacommons.org/v2/observation?key=...&date=LATEST&variable.dcids=Count_Person_Female&variable.dcids=Count_Person_Male&entity.dcids=country/CAN&entity.dcids=country/MEX&entity.dcids=country/SGP&entity.dcids=country/MYS&select=entity&select=variable&select=date&select=value
> '
> {"byVariable":{"Count_Person_Female":{"byEntity":{"country/SGP":{},"country/MYS":{},"country/CAN":{"orderedFacets":[{"facetId":"1151455814","observations":[{"date":"2023","value":20084054}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"4181918134","observations":[{"date":"2023","value":20084054}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"1216205004","observations":[{"date":"2021","value":15839460}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","observations":[{"date":"2021","value":65833180}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"1151455814","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"4181918134","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"3614729857","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"}]}}},"Count_Person_Male":{"byEntity":{"country/MYS":{},"country/CAN":{"orderedFacets":[{"facetId":"1151455814","observations":[{"date":"2023","value":20013707}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"4181918134","observations":[{"date":"2023","value":20013707}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"1216205004","observations":[{"date":"2021","value":15139730}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","observations":[{"date":"2021","value":63139259}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"1151455814","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"4181918134","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"3614729857","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"}]},"country/SGP":{}}}},"facets":{"1151455814":{"importName":"OECDRegionalDemography","provenanceUrl":"
> https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR#
> ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"4181918134":{"importName":"OECDRegionalDemography_Population","provenanceUrl":"
>
> https://data-explorer.oecd.org/vis?fs[0]=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df[ds]=dsDisseminateFinalDMZ&df[id]=DSD_REG_DEMO%40DF_POP_5Y&df[ag]=OECD.CFE.EDS&df[vs]=2.0&dq=A.......&to[TIME_PERIOD]=false&vw=tb&pd=%2C
> <https://data-explorer.oecd.org/vis?fs%5B0%5D=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df%5Bds%5D=dsDisseminateFinalDMZ&df%5Bid%5D=DSD_REG_DEMO%40DF_POP_5Y&df%5Bag%5D=OECD.CFE.EDS&df%5Bvs%5D=2.0&dq=A.......&to%5BTIME_PERIOD%5D=false&vw=tb&pd=%2C>
> ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1216205004":{"importName":"CanadaStatistics","provenanceUrl":"
> https://www150.statcan.gc.ca/n1/en/type/data?MM=1
> "},"3251078590":{"importName":"MexicoCensus_AA2","provenanceUrl":"
> https://data.humdata.org/dataset/cod-ps-mex "},"3614729857
> <(361)%20472-9857>":{"importName":"MexicoCensus","provenanceUrl":"
> https://www.inegi.org.mx/temas/"}}}
> … <#m_-6207446057152575249_>
> On Thu, Mar 20, 2025 at 10:04 AM Kara Moscoe *@*.*> wrote: Er, honestly I
> don't see any difference between them. The only difference I could find is
> that the one with only "facet" omitted entities with no results, while the
> other includes them with empty brackets. On Thu, Mar 20, 2025 at 9:52 AM
> Dan Noble @.*> wrote: > Good find @jm-rivera
> <https://github.com/jm-rivera> https://github.com/jm-rivera - i didn't
> realize > we hadn't documented this. > > We use this functionality in the
> visualization tools facet selector to > let users pick what data
> source/facet to show. It's also used as way to do > a data 'existence
> check' in the natural language search endpoint to check > if data exists
> without actually fetching it. > > Kara: here are some working curl examples
> that fetch facets only and > facets + observations for datacommons.one.org:
> > > # Fetch facets only, no observations are returned > curl --request POST
> \ > --url https://datacommons.one.org/core/api/v2/observation \ > --data
> '{ > "select": ["variable", "entity", "facet"], > "entity": { > "dcids":
> ["country/NER"] > }, > "variable": { > "dcids":
> ["climateFinanceReceivedCommitments"] > } > }' > > # Fetch observation
> values, which also includes the facets > curl --request POST \ > --url
> https://datacommons.one.org/core/api/v2/observation \ > --data '{ >
> "select": ["variable", "entity", "date", "value"], > "entity": { > "dcids":
> ["country/NER"] > }, > "variable": { > "dcids":
> ["climateFinanceReceivedCommitments"] > } > }' > > — > Reply to this email
> directly, view it on GitHub > <#224 (comment)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>>,
> > or unsubscribe >
> https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM
> > . > You are receiving this because you were mentioned.Message ID: > *@*.*>
> > [image: dwnoble]dwnoble left a comment (datacommonsorg/api-python#224
> <https://github.com/datacommonsorg/api-python/pull/224>) > <#224 (comment)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>>
> > > Good find @jm-rivera <https://github.com/jm-rivera>
> https://github.com/jm-rivera <https://github.com/jm-rivera> - i didn't
> realize > we hadn't documented this. > > We use this functionality in the
> visualization tools facet selector to > let users pick what data
> source/facet to show. It's also used as way to do > a data 'existence
> check' in the natural language search endpoint to check > if data exists
> without actually fetching it. > > Kara: here are some working curl examples
> that fetch facets only and > facets + observations for datacommons.one.org
> <http://datacommons.one.org>: > > # Fetch facets only, no observations are
> returned > curl --request POST \ > --url
> https://datacommons.one.org/core/api/v2/observation
> <https://datacommons.one.org/core/api/v2/observation> \ > --data '{ >
> "select": ["variable", "entity", "facet"], > "entity": { > "dcids":
> ["country/NER"] > }, > "variable": { > "dcids":
> ["climateFinanceReceivedCommitments"] > } > }' > > # Fetch observation
> values, which also includes the facets > curl --request POST \ > --url
> https://datacommons.one.org/core/api/v2/observation
> <https://datacommons.one.org/core/api/v2/observation> \ > --data '{ >
> "select": ["variable", "entity", "date", "value"], > "entity": { > "dcids":
> ["country/NER"] > }, > "variable": { > "dcids":
> ["climateFinanceReceivedCommitments"] > } > }' > > — > Reply to this email
> directly, view it on GitHub > <#224 (comment)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>>,
> > or unsubscribe >
> https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM
> <https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM>
> > . > You are receiving this because you were mentioned.Message ID: > @.*>
> >
>
> This example looks like it's working to me -- the first request returns
> only facets for each requested entity, and the second returns the facets +
> latest observation for each requested entity
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741271457>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UCG4XHIN7PBWYB645T2VL7HDAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGI3TCNBVG4>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
> [image: dwnoble]*dwnoble* left a comment (datacommonsorg/api-python#224)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741271457>
>
> OMG, I see the difference: POST requests behave as you say, but GET
> requests do not!! Here's my test cases (key redacted): curl --request GET
> --url '
> https://api.datacommons.org/v2/observation?key=...&date=LATEST&variable.dcids=Count_Person_Female&variable.dcids=Count_Person_Male&entity.dcids=country/CAN&entity.dcids=country/MEX&entity.dcids=country/SGP&entity.dcids=country/MYS&select=entity&select=variable&select=facet
> '
> {"byVariable":{"Count_Person_Female":{"byEntity":{"country/CAN":{"orderedFacets":[{"facetId":"4181918134","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1151455814","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1216205004","obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"4181918134","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"1151455814","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"3614729857","obsCount":6,"earliestDate":"1990","latestDate":"2020"}]}}},"Count_Person_Male":{"byEntity":{"country/CAN":{"orderedFacets":[{"facetId":"4181918134","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1151455814","obsCount":34,"earliestDate":"1990","latestDate":"2023"},{"facetId":"1216205004","obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"4181918134","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"1151455814","obsCount":31,"earliestDate":"1990","latestDate":"2020"},{"facetId":"3614729857","obsCount":6,"earliestDate":"1990","latestDate":"2020"}]}}}},"facets":{"4181918134":{"importName":"OECDRegionalDemography_Population","provenanceUrl":"
>
> https://data-explorer.oecd.org/vis?fs[0]=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df[ds]=dsDisseminateFinalDMZ&df[id]=DSD_REG_DEMO%40DF_POP_5Y&df[ag]=OECD.CFE.EDS&df[vs]=2.0&dq=A.......&to[TIME_PERIOD]=false&vw=tb&pd=%2C
> <https://data-explorer.oecd.org/vis?fs%5B0%5D=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df%5Bds%5D=dsDisseminateFinalDMZ&df%5Bid%5D=DSD_REG_DEMO%40DF_POP_5Y&df%5Bag%5D=OECD.CFE.EDS&df%5Bvs%5D=2.0&dq=A.......&to%5BTIME_PERIOD%5D=false&vw=tb&pd=%2C>
> ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1151455814":{"importName":"OECDRegionalDemography","provenanceUrl":"
> https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR#
> ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1216205004":{"importName":"CanadaStatistics","provenanceUrl":"
> https://www150.statcan.gc.ca/n1/en/type/data?MM=1
> "},"3251078590":{"importName":"MexicoCensus_AA2","provenanceUrl":"
> https://data.humdata.org/dataset/cod-ps-mex "},"3614729857
> <(361)%20472-9857>":{"importName":"MexicoCensus","provenanceUrl":"
> https://www.inegi.org.mx/temas/"}}} $ curl --request GET --url '
> https://api.datacommons.org/v2/observation?key=...&date=LATEST&variable.dcids=Count_Person_Female&variable.dcids=Count_Person_Male&entity.dcids=country/CAN&entity.dcids=country/MEX&entity.dcids=country/SGP&entity.dcids=country/MYS&select=entity&select=variable&select=date&select=value
> '
> {"byVariable":{"Count_Person_Female":{"byEntity":{"country/SGP":{},"country/MYS":{},"country/CAN":{"orderedFacets":[{"facetId":"1151455814","observations":[{"date":"2023","value":20084054}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"4181918134","observations":[{"date":"2023","value":20084054}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"1216205004","observations":[{"date":"2021","value":15839460}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","observations":[{"date":"2021","value":65833180}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"1151455814","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"4181918134","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"3614729857","observations":[{"date":"2020","value":64540634}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"}]}}},"Count_Person_Male":{"byEntity":{"country/MYS":{},"country/CAN":{"orderedFacets":[{"facetId":"1151455814","observations":[{"date":"2023","value":20013707}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"4181918134","observations":[{"date":"2023","value":20013707}],"obsCount":1,"earliestDate":"2023","latestDate":"2023"},{"facetId":"1216205004","observations":[{"date":"2021","value":15139730}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"}]},"country/MEX":{"orderedFacets":[{"facetId":"3251078590","observations":[{"date":"2021","value":63139259}],"obsCount":1,"earliestDate":"2021","latestDate":"2021"},{"facetId":"1151455814","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"4181918134","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"},{"facetId":"3614729857","observations":[{"date":"2020","value":61473390}],"obsCount":1,"earliestDate":"2020","latestDate":"2020"}]},"country/SGP":{}}}},"facets":{"1151455814":{"importName":"OECDRegionalDemography","provenanceUrl":"
> https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR#
> ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"4181918134":{"importName":"OECDRegionalDemography_Population","provenanceUrl":"
>
> https://data-explorer.oecd.org/vis?fs[0]=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df[ds]=dsDisseminateFinalDMZ&df[id]=DSD_REG_DEMO%40DF_POP_5Y&df[ag]=OECD.CFE.EDS&df[vs]=2.0&dq=A.......&to[TIME_PERIOD]=false&vw=tb&pd=%2C
> <https://data-explorer.oecd.org/vis?fs%5B0%5D=Topic%2C0%7CRegional%252C%20rural%20and%20urban%20development%23GEO%23&pg=40&fc=Topic&bp=true&snb=117&df%5Bds%5D=dsDisseminateFinalDMZ&df%5Bid%5D=DSD_REG_DEMO%40DF_POP_5Y&df%5Bag%5D=OECD.CFE.EDS&df%5Bvs%5D=2.0&dq=A.......&to%5BTIME_PERIOD%5D=false&vw=tb&pd=%2C>
> ","measurementMethod":"OECDRegionalStatistics","observationPeriod":"P1Y"},"1216205004":{"importName":"CanadaStatistics","provenanceUrl":"
> https://www150.statcan.gc.ca/n1/en/type/data?MM=1
> "},"3251078590":{"importName":"MexicoCensus_AA2","provenanceUrl":"
> https://data.humdata.org/dataset/cod-ps-mex "},"3614729857
> <(361)%20472-9857>":{"importName":"MexicoCensus","provenanceUrl":"
> https://www.inegi.org.mx/temas/"}}}
> … <#m_-6207446057152575249_>
> On Thu, Mar 20, 2025 at 10:04 AM Kara Moscoe *@*.*> wrote: Er, honestly I
> don't see any difference between them. The only difference I could find is
> that the one with only "facet" omitted entities with no results, while the
> other includes them with empty brackets. On Thu, Mar 20, 2025 at 9:52 AM
> Dan Noble @.*> wrote: > Good find @jm-rivera
> <https://github.com/jm-rivera> https://github.com/jm-rivera - i didn't
> realize > we hadn't documented this. > > We use this functionality in the
> visualization tools facet selector to > let users pick what data
> source/facet to show. It's also used as way to do > a data 'existence
> check' in the natural language search endpoint to check > if data exists
> without actually fetching it. > > Kara: here are some working curl examples
> that fetch facets only and > facets + observations for datacommons.one.org:
> > > # Fetch facets only, no observations are returned > curl --request POST
> \ > --url https://datacommons.one.org/core/api/v2/observation \ > --data
> '{ > "select": ["variable", "entity", "facet"], > "entity": { > "dcids":
> ["country/NER"] > }, > "variable": { > "dcids":
> ["climateFinanceReceivedCommitments"] > } > }' > > # Fetch observation
> values, which also includes the facets > curl --request POST \ > --url
> https://datacommons.one.org/core/api/v2/observation \ > --data '{ >
> "select": ["variable", "entity", "date", "value"], > "entity": { > "dcids":
> ["country/NER"] > }, > "variable": { > "dcids":
> ["climateFinanceReceivedCommitments"] > } > }' > > — > Reply to this email
> directly, view it on GitHub > <#224 (comment)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>>,
> > or unsubscribe >
> https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM
> > . > You are receiving this because you were mentioned.Message ID: > *@*.*>
> > [image: dwnoble]dwnoble left a comment (datacommonsorg/api-python#224
> <https://github.com/datacommonsorg/api-python/pull/224>) > <#224 (comment)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>>
> > > Good find @jm-rivera <https://github.com/jm-rivera>
> https://github.com/jm-rivera <https://github.com/jm-rivera> - i didn't
> realize > we hadn't documented this. > > We use this functionality in the
> visualization tools facet selector to > let users pick what data
> source/facet to show. It's also used as way to do > a data 'existence
> check' in the natural language search endpoint to check > if data exists
> without actually fetching it. > > Kara: here are some working curl examples
> that fetch facets only and > facets + observations for datacommons.one.org
> <http://datacommons.one.org>: > > # Fetch facets only, no observations are
> returned > curl --request POST \ > --url
> https://datacommons.one.org/core/api/v2/observation
> <https://datacommons.one.org/core/api/v2/observation> \ > --data '{ >
> "select": ["variable", "entity", "facet"], > "entity": { > "dcids":
> ["country/NER"] > }, > "variable": { > "dcids":
> ["climateFinanceReceivedCommitments"] > } > }' > > # Fetch observation
> values, which also includes the facets > curl --request POST \ > --url
> https://datacommons.one.org/core/api/v2/observation
> <https://datacommons.one.org/core/api/v2/observation> \ > --data '{ >
> "select": ["variable", "entity", "date", "value"], > "entity": { > "dcids":
> ["country/NER"] > }, > "variable": { > "dcids":
> ["climateFinanceReceivedCommitments"] > } > }' > > — > Reply to this email
> directly, view it on GitHub > <#224 (comment)
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741098333>>,
> > or unsubscribe >
> https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM
> <https://github.com/notifications/unsubscribe-auth/BHMM7UDDCVQVSK24U3FIEYL2VLW47AVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGA4TQMZTGM>
> > . > You are receiving this because you were mentioned.Message ID: > @.*>
> >
>
> This example looks like it's working to me -- the first request returns
> only facets for each requested entity, and the second returns the facets +
> latest observation for each requested entity
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/datacommonsorg/api-python/pull/224#issuecomment-2741271457>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BHMM7UCG4XHIN7PBWYB645T2VL7HDAVCNFSM6AAAAABZNSMEM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBRGI3TCNBVG4>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>

author_association: CONTRIBUTOR