List GeoNames children
geonames_get_childrenList the direct children of a GeoNames feature — Earth's continents, a continent's countries, a country's first-level divisions, a state's counties, a city's sections — in the administrative tree, or in the tourism tree (islands, coasts, and their municipalities; almost all in Spain) or the dependency tree (a country's dependent territories). Start from a country's geonameId (geonames_get_countries) or any admin division's. Children are mostly admin divisions (class A) and populated places (class P); continents and coasts are class L and islands class T. For other feature types inside a place, use geonames_search_places with a boundingBox. GeoNames answers a tourism or dependency request with the administrative children when the feature has no such tree, so the tool compares the two lists and sets sameAsAdministrative when they match, keeping the rows (a real tree can match too). The full child list is fetched once (1 GeoNames credit) and cached, so paging and nameContains filtering are free; a tourism or dependency call also reads the administrative list for the comparison, 1 more credit unless it is cached.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entries to return, 1 to 500. Default 100. | |
| offset | No | Entries to skip before the first one returned, for paging. Default 0. | |
| geonameId | Yes | GeoNames id of the parent feature, a positive integer up to 2147483647 such as 6252001 (United States), as returned in geonameId by the other geonames tools. A geonames.org/<id> URL is reduced to its id. | |
| hierarchy | No | Which tree to descend: administrative (the default: continents (class L), countries, admin divisions, populated places), tourism (islands (class T), coasts (class L), and their municipalities; almost all in Spain), or dependency (a country's dependent territories). For a feature with no tourism or dependency tree, GeoNames answers with its administrative children, which sameAsAdministrative flags; the comparison reads the administrative list, 1 more credit unless it is cached. Case-insensitive. | administrative |
| nameContains | No | Keep only children whose name or toponym name contains every word of this text as a substring (kansas also matches Arkansas), ignoring case, accents, and punctuation. | |
| geonamesUsername | No | Your own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit that was applied. | |
| error | No | Present when the call failed. Absent on success. | |
| found | No | False when GeoNames has no feature with this geonameId. | |
| shown | No | Children returned on this page. | |
| notice | No | Guidance when a tourism or dependency answer is the administrative children, there are no children, nothing matched, the offset is past the end, more pages remain, or GeoNames holds more children than it returns. | |
| children | No | Children on this page, in GeoNames' order; empty when found is false or the feature has none. | |
| guidance | No | What to do next; present only when found is false. | |
| hierarchy | No | The tree that was descended. | |
| truncated | No | True when more children remain past this page. | |
| nextOffset | No | Offset of the next page; absent on the last page. | |
| totalCount | No | Children matching nameContains, before paging. | |
| parentGeonameId | No | The geonameId whose children were requested. | |
| sameAsAdministrative | No | Tourism and dependency trees only, when the feature has children there: true when they are exactly its administrative children (same geonameIds and total). GeoNames answers with the administrative children when a feature has no such tree, so true most likely means it has none; a real tree can also match. |