YQL Tables

Summary of YQL Tables

The GeoPlanet Web Service can be accessed through the following set of YQL tables:

  • geo.places: Returns information about a place or places.
  • geo.places.parent: Returns information about the parent of a place.
  • geo.places.ancestors: Returns information about places in the parent hierarchy for a place.
  • geo.places.belongtos: Returns information about places that contain a place.
  • geo.places.neighbors: Returns information about places that are neighbors of a place.
  • geo.places.siblings: Returns information about places that are siblings of a place.
  • geo.places.children: Returns information about places that are children of a place.
  • geo.places.descendants: Returns information about places that are descendants of a place.
  • geo.places.common: Returns information about the place that is a common ancestor to two or more places. Up to seven places can provided.
  • geo.continents: Returns information about places that are continents.
  • geo.oceans: Returns information about places that are oceans.
  • geo.seas: Returns information about places that are seas, bays, or channels.
  • geo.countries: Returns information about places that are countries or dependent territories.
  • geo.states: Returns information about places that are first-level administrative areas within a country.
  • geo.counties: Returns information about places that are second-level administrative areas within a country.
  • geo.districts: Returns information about places that are third-level administrative areas within a country.
  • geo.concordance: Returns information about place identifiers used to refer to a place.
  • geo.placetypes: Returns information about a placetype or placetypes.

geo.places

The geo.places table returns information about a place or places.

Key Name Optional/Required Description
woeid (see below) WOEID
text (see below) location text
focus optional place focus WOEID or country code
placetype optional placetype name(s) or code(s)
lang optional desired language for place names (ISO 639)

Woeid and text are mutually exclusive and one of these parameters is required. Focus and placetype are only allowed with text is provided.

Example:

Find places named 'SFO':

select * from geo.places where text = 'SFO'

geo.places.parent

The geo.places.parent table returns information about the parent of a place.

Key Name Optional/Required Description
child_woeid required WOEID of child place
lang optional desired language for place names (ISO 639)

Example:

Find the parent place of Sunnyvale, CA:

select * from geo.places.parent where child_woeid in (select woeid from geo.places where text='sunnyvale, ca')

geo.places.ancestors

The geo.places.ancestors table returns information about places in the parent hierarchy for a place.

Key Name Optional/Required Description
descendant_woeid required WOEID of the descendant place
lang optional desired language for place names (ISO 639)

Example:

Find all administrative places containing Sunnyvale, CA:

select * from geo.places.ancestors where descendant_woeid in (select woeid from geo.places where text='sunnyvale, ca')

geo.places.belongtos

The geo.places.belongtos table returns information about places that contain a place.

Key Name Optional/Required Description
member_woeid required WOEID of the member place
placetype optional placetype name(s) or code(s)
lang optional desired language for place names (ISO 639)

Example:

Find all places containing Sunnyvale, CA:

select * from geo.places.belongtos where member_woeid in (select woeid from geo.places where text='sunnyvale, ca')

geo.places.neighbors

The geo.places.neighbors table returns information about places that are neighbors of a place.

Key Name Optional/Required Description
neighbor_woeid required WOEID of neighbor place
lang optional desired language for place names (ISO 639)

Example:

Find all neighboring towns of Sunnyvale, CA:

select * from geo.places.neighbors where neighbor_woeid in (select woeid from geo.places where text='sunnyvale, ca')

geo.places.siblings

The geo.places.siblings table returns information about places that are siblings of a place.

Key Name Optional/Required Description
sibling_woeid required WOEID of sibling place
lang optional desired language for place names (ISO 639)

Example:

Find all sibling towns of Sunnyvale, CA:

select * from geo.places.siblings where sibling_woeid in (select woeid from geo.places where text='sunnyvale, ca')

geo.places.children

The geo.places.children table returns information about places that are children of a place.

Key Name Optional/Required Description
parent_woeid required WOEID of parent place
placetype optional placetype name(s) or code(s)
lang optional desired language for place names (ISO 639)

Example:

Find all children of Sunnyvale, CA:

select * from geo.places.children where parent_woeid in (select woeid from geo.places where text='sunnyvale, ca')

geo.places.descendants

The geo.places.descendants table returns information about places that are descendants of a place.

Key Name Optional/Required Description
ancestor_woeid required WOEID of ancestor place
placetype optional placetype name(s) or code(s)
degree optional
view optional desired view (short or long)
lang optional desired language for place names (ISO 639)

Example:

Find all descendeants of Sunnyvale, CA:

select placeTypeName, name from geo.places.descendants where ancestor_woeid in (select woeid from geo.places where text='sunnyvale, ca')

geo.places.common

The geo.places.common table returns information about the place that is a common ancestor to two or more places. Up to seven places can provided.

Key Name Optional/Required Description
woeid1 required WOEID of first descendant place
woeid2 required WOEID of second descendant place
woeid3 optional* WOEID of additional place
woeid4 optional* WOEID of additional place
woeid5 optional* WOEID of additional place
woeid6 optional* WOEID of additional place
woeid7 optional* WOEID of additional place
view optional desired view (short or long)
lang optional desired language for place names (ISO 639)

* woeid fields are required if a higher numbered woeid parameter is provided. For example, if woeid5 is provided, then woeid4 is required as well.

Note that only one subselect is allowed in a YQL query.

Example:

Find the common ancestor of Sunnyvale, CA and San Jose, CA (WOEID 2488042):

select placeTypeName, name from geo.places.common where woeid1 in (select woeid from geo.places where text='sunnyvale, ca') and woeid2=2488042

geo.continents

The geo.continents table returns information about places that are continents.

Key Name Optional/Required Description
view optional desired view (short or long)
lang optional desired language for place names (ISO 639)

Example:

Find all continents:

select * from geo.continents

geo.oceans

The geo.oceans table returns information about places that are oceans.

Key Name Optional/Required Description
view optional desired view (short or long)
lang optional desired language for place names (ISO 639)

Example:

Find all oceans:

select * from geo.oceans

geo.seas

The geo.seas table returns information about places that are seas, bays, or channels.

Key Name Optional/Required Description
place optional Continent WOEID, Continent or Ocean code, or name
view optional desired view (short or long)
lang optional desired language for place names (ISO 639)

If place is provided the table is filtered for seas that are adjacent to that place.

Example:

Find all seas adjacent to North America:

select * from geo.seas where place='North America'

geo.countries

The geo.countries table returns information about places that are countries or dependent territories.

Key Name Optional/Required Description
place optional Continent WOEID, Continent or Ocean code, or name
view optional desired view (short or long)
lang optional desired language for place names (ISO 639)

If place is provided the table is filtered for seas that are adjacent to that place.

Example:

Find all countries within North America:

select * from geo.countries where place='North America'

geo.states

The geo.states table returns information about places that are first-level administrative areas within a country.

Note that the term "state" refers to any administrative area that subdives a country, such as states, districts, territories, provinces, prefectures, governates, constituent countries, regions.

Key Name Optional/Required Description
place required Country WOEID, code (ISO 3166-1), or name
view optional desired view (short or long)
lang optional desired language for place names (ISO 639)

Example:

Find all states within United States:

select * from geo.states where place='United States'

geo.counties

The geo.counties table returns information about places that are second-level administrative areas within a country.

Note that the term "county" refers to any administrative area that subdivides a first-level administrative area, such as counties, parishes, boroughs, departments, provinces, districts.

Key Name Optional/Required Description
place required State WOEID, code (ISO 3166-2), or name
view optional desired view (short or long)
lang optional desired language for place names (ISO 639)

Example:

Find all counties within California:

select * from geo.counties where place='California'

geo.districts

The geo.districts table returns information about places that are third-level administrative areas within a country.

Note that the term "district" refers to any administrative area that subdivides a second-level administrative area, such as districts, communes, municipalities.

Key Name Optional/Required Description
place required County WOEID, code (ISO 3166-2), or name
view optional desired view (short or long)
lang optional desired language for place names (ISO 639)

Example:

Find all districts within Greater London:

select * from geo.districts where place='Greater London'

geo.concordance

The geo.concordance table returns information about place identifiers used to refer to a place.

Key Name Optional/Required Description
namespace required namespace for place identifier
text required place identifier
lang optional desired language for place names (ISO 639)

Example:

Find place identifers for SFO airport code:

select * from geo.concordance where namespace='IATA' and text='SFO'

geo.placetypes

The geo.placetypes table returns information about a placetype or placetypes.

Key Name Optional/Required Description
placetype optional placetype name
placetypeid optional placetype id
lang optional desired language for place names (ISO 639)

Placetype and placetypeid are mutually exclusive; if one is provided, the other may not be provided.

Example:

Return information about all placetypes:

select * from geo.placetypes

Table of Contents