The population number has a period

A population figure on a city page needs a date. Someone comparing two places should be able to tell whether their estimates describe the same period. Fetching both numbers on the same day does not establish that.

In API 2.0.0, paid country, state, district, city and postal profiles return population_period beside population inside deep. Ask for that detail with ?deep=true. For example, the country lookup accepts:

GET /country/US?deep=true

The period is a string in YYYY or YYYY-YYYY form. A single year identifies the estimate's observation year. A range identifies a multi-year observation period. Keep that range intact in your interface. Shortening it to its last year would make it look like a single-year estimate.

This date belongs to the statistic. It is not the day you made the request or the day ParseAPI received the data. A newly retrieved number can still describe an earlier year. Refreshing a place page should not quietly change its caption to "Population in 2026" just because the page was refreshed in 2026.

If you save the population in your own database or export, save its period alongside it. You can record a separate fetch date when that is useful, but the two dates answer different questions. The period also does not establish that two estimates use the same geographic boundaries or method.

Some records have a population but no known observation period. Those return population_period: null. Leave the date unspecified rather than filling in the current year. Continent totals combine country estimates that can have different periods, so Continent does not expose this field at all. A total does not acquire a common date just because the numbers were added together.