API doc for new REST endpoint: /place/stat/date/within-place

[beets]

This endpoint allows a user to retrieve dates with data available for each statistical variable specified. The set of places to query is specified by an ancestor place, and the place type of the child places to consider (similar to our places-in API). This is helpful for building an interactive app to explore our data, e.g. https://staging.datacommons.org/tools/scatter2

Endpoint: /place/stat/date/within-place (code)

Params:

• ancestor_place
• place_type
• stat_vars (repeated list of stat_vars accepted)

Available as both GET and POST

Request: curl -X POST https://api.datacommons.org/place/stat/date/within-place -d '{ "ancestor_place": "geoId/06”, “place_type”: “City”, “stat_vars”: [“Count_Person”]}'
Response: {“Count_Person”: [“2017”, “2018”, ...]}

or

https://api.datacommons.org/place/stat/date/within-place?ancestor_place=geoId/06&place_type=County&stat_vars=Count_Person&stat_vars=Count_Person_Female

/cc: @shifucun

[beets]

@shifucun are direct ancestor relationships required? or is there a subset of places that this works for?

e.g.
https://api.datacommons.org/place/stat/date/within-place?ancestor_place=country/USA&place_type=County&stat_vars=Count_Person&stat_vars= Percent_Person_SleepLessThan7Hours
https://api.datacommons.org/place/stat/date/within-place?ancestor_place=Earth&place_type=Country&stat_vars=Count_Person

[beets]

@KilimAnnejaro the scatterplot tool is an example of an app that would need this feature - we shouldn't mention it since it's not launched yet

[beets]

Ah, spoke with Bo and it looks like a direct ancestor relationship is required (i.e. must have a direct containedInPlace relationship)

Here are a few working examples:
https://api.datacommons.org/place/stat/date/within-place?ancestor_place=geoId/06&place_type=City&stat_vars=Percent_Person_SleepLessThan7Hours
https://api.datacommons.org/place/stat/date/within-place?ancestor_place=northamerica&place_type=Country&stat_vars=Count_Person_Male&stat_vars=Count_Person_Female