Skip to content

Commit e244b63

Browse files
kmoscoegemini-code-assist[bot]clincoln8
authored
Add fields missing from facets in observation response (#694)
* remove references to dataclass objects * Fix a copy-paste error. * remove extra file * Fix a copy-paste error. * Remove unused file * Start draft on new resolver parameters * first draft of new resolve API * First complete draft of new resolve API parameter * cut redundant text * Remove cohort from glossary * Update api/python/v2/resolve.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update api/python/v2/resolve.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * minor fixes from Gemini * Update api/python/v2/resolve.md Co-authored-by: Christie Ellks <calinc@google.com> * Some changes from Christie * minor changes * Update api/rest/v2/resolve.md Co-authored-by: Christie Ellks <calinc@google.com> * Update api/rest/v2/resolve.md Co-authored-by: Christie Ellks <calinc@google.com> * Update api/rest/v2/resolve.md Co-authored-by: Christie Ellks <calinc@google.com> * Update api/rest/v2/resolve.md Co-authored-by: Christie Ellks <calinc@google.com> * changes from Christie * Changes for consistency * small fix from Christie * Updates to data model page * Update data_model.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Remove link * Remove all V1 API docs (including Python) and references to SPARQL * Fix fields missing from facets and change one example * Wording change * Add descriptions of all facet fields and remove duplication from Python doc * Apply changes to Python * Add brackets to indicate optionality in response fields * Remove duplication in response field tables * Add missing type from dcid response field * Correct candidates type * Fix field names * Fix date copy-paste error * Expand is_dc_aggregate definition to include event statvars --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Co-authored-by: Christie Ellks <calinc@google.com>
1 parent 1b63c12 commit e244b63

4 files changed

Lines changed: 128 additions & 506 deletions

File tree

‎api/python/v2/observation.md‎

Lines changed: 69 additions & 201 deletions
Original file line numberDiff line numberDiff line change
@@ -65,10 +65,13 @@ With `select=["date", "entity", "variable", "value"]` in effect (the default), t
6565
}
6666
"facets" {
6767
"<var>FACET_ID</var>": {
68-
"importName": "...",
69-
"provenanceUrl": "...",
70-
"measurementMethod": "...",
71-
"observationPeriod": "..."
68+
"importName": "<var>DATASET_NAME</var>",
69+
"provenanceUrl": "<var>DATASET_URL</var>",
70+
["measurementMethod": "<var>MEASUREMENT_METHOD</var>",]
71+
["observationPeriod": "<var>TIME_PERIOD</var>",]
72+
["scalingFactor": "<var>NUMBER</var>",]
73+
["unit": "<var>UNIT</var>",]
74+
["isDcAggregate": "true" | "false"]
7275
},
7376
...
7477
}
@@ -115,10 +118,13 @@ With `select=["variable", "entity", "facet"]`, the response looks like:
115118
}
116119
"facets" {
117120
"<var>FACET_ID</var>": {
118-
"importName": "...",
119-
"provenanceUrl": "...",
120-
"measurementMethod": "...",
121-
"observationPeriod": "..."
121+
"importName": "<var>DATASET_NAME</var>",
122+
"provenanceUrl": "<var>DATASET_URL</var>",
123+
["measurementMethod": "<var>MEASUREMENT_METHOD</var>",]
124+
["observationPeriod": "<var>TIME_PERIOD</var>",]
125+
["scalingFactor": "<var>NUMBER</var>",]
126+
["unit": "<var>UNIT</var>",]
127+
["isDcAggregate": "true" | "false"]
122128
},
123129
...
124130
}
@@ -131,12 +137,7 @@ There are additional methods you can call on the response to structure the data
131137

132138
### Response fields
133139

134-
| Name | Type | Description |
135-
|-------------|--------|-------------------------------------|
136-
| orderedFacets | list of objects | Metadata about the observations returned, keyed first by variable, and then by entity. These include the date range, the number of observations included in the facet and so on. |
137-
| observations | list of objects | Date and value pairs for the observations made in the time period. |
138-
| facets | object | Various properties of reported facets, where available, including the provenance of the data, the import name, date range of observations, etc. |
139-
{: .doc-table}
140+
See [v2/observation](/api/rest/v2/observation.html#response-fields) for details.
140141

141142
### Response property methods
142143

@@ -879,208 +880,75 @@ Response:
879880
```
880881

881882
{: .no_toc}
882-
#### Example 3: Get the observations at a particular date for given entities by DCID
883+
#### Example 3: Get the observations at a particular date for multiple entities by DCID
883884

884-
This gets observations for the populations of the U.S.A. and California in 2015. It uses the same variable as the previous example, two entities, and a specific date.
885+
This gets observations for the median household income of the U.S.A. and California in 2015. It uses one variable, two entities, and a specific date.
885886

886887
Request:
887888
{: .example-box-title}
888889

889890
```python
890-
client.observation.fetch_observations_by_entity_dcid(date="2015", entity_dcids=["country/USA", "geoId/06"], variable_dcids="Count_Person")
891+
client.observation.fetch_observations_by_entity_dcid(date="2015", entity_dcids=["country/USA", "geoId/06"], variable_dcids="Median_Income_Household")
891892
```
892893
{: .example-box-content .scroll}
893894

894-
> Tip: This example is the equivalent of `client.observation.fetch(variable_dcids="Count_Person", date="2015", entity_dcids=["country/USA", "geoId/06"])`
895+
> Tip: This example is the equivalent of `client.observation.fetch(variable_dcids="Median_Income_Household", date="2015", entity_dcids=["country/USA", "geoId/06"])`
895896

896897
Response:
897898
{: .example-box-title}
898899

899900
```python
900-
{
901-
"byVariable": {
902-
"Count_Person": {
903-
"byEntity": {
904-
"country/USA": {
905-
"orderedFacets": [
906-
{
907-
"facetId": "2176550201",
908-
"observations": [
909-
{
910-
"date": "2015",
911-
"value": 320738994
912-
}
913-
],
914-
"obsCount": 1,
915-
"earliestDate": "2015",
916-
"latestDate": "2015"
917-
},
918-
{
919-
"facetId": "2645850372",
920-
"observations": [
921-
{
922-
"date": "2015",
923-
"value": 320098094
924-
}
925-
],
926-
"obsCount": 1,
927-
"earliestDate": "2015",
928-
"latestDate": "2015"
929-
},
930-
{
931-
"facetId": "3981252704",
932-
"observations": [
933-
{
934-
"date": "2015",
935-
"value": 320738994
936-
}
937-
],
938-
"obsCount": 1,
939-
"earliestDate": "2015",
940-
"latestDate": "2015"
941-
},
942-
{
943-
"facetId": "1151455814",
944-
"observations": [
945-
{
946-
"date": "2015",
947-
"value": 320635163
948-
}
949-
],
950-
"obsCount": 1,
951-
"earliestDate": "2015",
952-
"latestDate": "2015"
953-
},
954-
...
955-
"geoId/06": {
956-
"orderedFacets": [
957-
{
958-
"facetId": "2176550201",
959-
"observations": [
960-
{
961-
"date": "2015",
962-
"value": 38904296
963-
}
964-
],
965-
"obsCount": 1,
966-
"earliestDate": "2015",
967-
"latestDate": "2015"
968-
},
969-
{
970-
"facetId": "1145703171",
971-
"observations": [
972-
{
973-
"date": "2015",
974-
"value": 38421464
975-
}
976-
],
977-
"obsCount": 1,
978-
"earliestDate": "2015",
979-
"latestDate": "2015"
980-
},
981-
{
982-
"facetId": "1151455814",
983-
"observations": [
984-
{
985-
"date": "2015",
986-
"value": 38918045
987-
}
988-
],
989-
"obsCount": 1,
990-
"earliestDate": "2015",
991-
"latestDate": "2015"
992-
},
993-
{
994-
"facetId": "4181918134",
995-
"observations": [
996-
{
997-
"date": "2015",
998-
"value": 38918045
999-
}
1000-
],
1001-
"obsCount": 1,
1002-
"earliestDate": "2015",
1003-
"latestDate": "2015"
1004-
},
1005-
{
1006-
"facetId": "10983471",
1007-
"observations": [
1008-
{
1009-
"date": "2015",
1010-
"value": 38421464
1011-
}
1012-
],
1013-
"obsCount": 1,
1014-
"earliestDate": "2015",
1015-
"latestDate": "2015"
1016-
},
1017-
...
1018-
{
1019-
"facetId": "2458695583",
1020-
"observations": [
1021-
{
1022-
"date": "2015",
1023-
"value": 39144818
1024-
}
1025-
],
1026-
"obsCount": 1,
1027-
"earliestDate": "2015",
1028-
"latestDate": "2015"
1029-
}
1030-
]
1031-
}
901+
{'byVariable':
902+
{'Median_Income_Household':
903+
{'byEntity':
904+
{'country/USA':
905+
{'orderedFacets': [
906+
{'earliestDate': '2015',
907+
'facetId': '1107922769',
908+
'latestDate': '2015',
909+
'obsCount': 1,
910+
'observations': [
911+
{'date': '2015', 'value': 53889.0}
912+
]
913+
}
914+
]
915+
},
916+
'geoId/06':
917+
{'orderedFacets': [
918+
{'earliestDate': '2015',
919+
'facetId': '1305418269',
920+
'latestDate': '2015',
921+
'obsCount': 1,
922+
'observations': [
923+
{'date': '2015', 'value': 61818.0}
924+
]
925+
},
926+
{'earliestDate': '2015',
927+
'facetId': '1107922769',
928+
'latestDate': '2015',
929+
'obsCount': 1,
930+
'observations': [{'date': '2015', 'value': 61818.0}
931+
]
932+
}
933+
]
934+
}
1032935
}
1033-
}
1034-
},
1035-
"facets": {
1036-
"1226172227": {
1037-
"importName": "CensusACS1YearSurvey",
1038-
"provenanceUrl": "https://www.census.gov/programs-surveys/acs/data/data-via-ftp.html",
1039-
"measurementMethod": "CensusACS1yrSurvey"
1040-
},
1041-
"2458695583": {
1042-
"importName": "WikidataPopulation",
1043-
"provenanceUrl": "https://www.wikidata.org/wiki/Wikidata:Main_Page",
1044-
"measurementMethod": "WikidataPopulation"
1045-
},
1046-
"3981252704": {
1047-
"importName": "WorldDevelopmentIndicators",
1048-
"provenanceUrl": "https://datacatalog.worldbank.org/dataset/world-development-indicators/",
1049-
"observationPeriod": "P1Y"
1050-
},
1051-
"4181918134": {
1052-
"importName": "OECDRegionalDemography_Population",
1053-
"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",
1054-
"measurementMethod": "OECDRegionalStatistics",
1055-
"observationPeriod": "P1Y"
1056-
},
1057-
"10983471": {
1058-
"importName": "CensusACS5YearSurvey_SubjectTables_S2601A",
1059-
"provenanceUrl": "https://data.census.gov/cedsci/table?q=S2601A&tid=ACSST5Y2019.S2601A",
1060-
"measurementMethod": "CensusACS5yrSurveySubjectTable"
1061-
},
1062-
"1964317807": {
1063-
"importName": "CensusACS5YearSurvey_SubjectTables_S0101",
1064-
"provenanceUrl": "https://data.census.gov/table?q=S0101:+Age+and+Sex&tid=ACSST1Y2022.S0101",
1065-
"measurementMethod": "CensusACS5yrSurveySubjectTable"
1066-
},
1067-
"2517965213": {
1068-
"importName": "CensusPEP",
1069-
"provenanceUrl": "https://www.census.gov/programs-surveys/popest.html",
1070-
"measurementMethod": "CensusPEPSurvey"
1071-
},
1072-
"2825511676": {
1073-
"importName": "CDC_Mortality_UnderlyingCause",
1074-
"provenanceUrl": "https://wonder.cdc.gov/ucd-icd10.html"
1075-
},
1076-
"1151455814": {
1077-
"importName": "OECDRegionalDemography",
1078-
"provenanceUrl": "https://stats.oecd.org/Index.aspx?DataSetCode=REGION_DEMOGR#",
1079-
"measurementMethod": "OECDRegionalStatistics",
1080-
"observationPeriod": "P1Y"
1081-
},
1082-
...
1083-
}
936+
}
937+
},
938+
'facets': {
939+
'1305418269':
940+
{'importName': 'CensusACS5YearSurvey',
941+
'measurementMethod': 'CensusACS5yrSurvey',
942+
'provenanceUrl': 'https://www.census.gov/programs-surveys/acs/data/data-via-ftp.html',
943+
'unit': 'USDollar'
944+
},
945+
'1107922769': {
946+
'importName': 'CensusACS5YearSurvey_SubjectTables_S1901',
947+
'measurementMethod': 'CensusACS5yrSurveySubjectTable',
948+
'provenanceUrl': 'https://data.census.gov/cedsci/table?q=S1901&tid=ACSST5Y2023.S1901',
949+
'unit': 'InflationAdjustedUSD_CurrentYear'
950+
}
951+
}
1084952
}
1085953
```
1086954
{: .example-box-content .scroll}

‎api/python/v2/resolve.md‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -129,17 +129,7 @@ For the methods `fetch_indicators` and `fetch` with the `resolver` parameter set
129129

130130
### Response fields
131131

132-
| Name | Type | Description |
133-
|-------------|--------|-------------------------------------|
134-
| node | string | The query terms used to look up the DCIDs of entities. |
135-
| candidates | list | List of nodes that match the query terms. Each node contains a DCID and (optionally) metadata and type information. |
136-
| dcid | The DCID of the candidate node. |
137-
| dominantType | string | Optional field which, when present, disambiguates between multiple results. Only returned when `resolver` is set to `place` (the default). |
138-
| metadata.score | float | The confidence score for the result, used to rank multiple results. Only returned when `resolver` is set to `indicator`. |
139-
| metadata.sentence | string | The matching substring contained in the node's name or description. Only returned when `resolver` is set to `indicator`. |
140-
| typeOf | string or list of strings | The type of the result. Currently supports only `StatisticalVariable` and `Topic`. Only returned when `resolver` is set to `indicator`. |
141-
{: .doc-table}
142-
132+
See [v2/resolve](/api/rest/v2/resolve.html#response-fields) for details.
143133

144134
### Response property methods
145135

0 commit comments

Comments
 (0)