A resource identifies an object (commonly referred to as "nouns" in REST terminology). For example, a named place is a resource, and a unique URL exists to retrieve it. Resources are referred to in the singular ('place', 'parent', etc.).
A collection is a list of resources. Whenever zero or more objects can be returned, a collection is used. Collections are referred to in the plural ('ancestors', 'children', etc.).
The Web service supports a number of different filters that allow you to select a subset of potentially large collections. Filters follow the collection name they refer to. A filter description consists of the filter name, an open parenthesis ("("), a list of numeric or string value separated by commas (","), and a close parenthesis (")"). If a string value contains a comma, the string value must be enclosed in single quotes ("'").
The following filters are provided by the Web service:
| Filter | Collection | Example | description |
|---|---|---|---|
.q(place [, focus])
|
/places
|
.q('Springfield')
|
Default. Returns places matching specified place and optional focus. This is a required filter for the /places collection. Refer to /places section for more details. |
.type(placetype)
|
/places
|
.type(country)
|
Returns places matching specified place type. Up to seven place types may be provided by separating them with commas. This filter can only be used in conjunction with the $and filter, since .q is a required filter for the /places collection. Refer to /places section for more details. |
.type(placetype)
|
|
.type(country)
|
Default. Returns places or place types matching specified place type. Up to seven place types may be provided by separating them with commas. Refer to /belongtos section for more details. |
$and(filter, filter)
|
/places
|
$and(.q(Springfield),.type(suburb))
|
Returns places matching the intersection of two filters. $and may not be one of the filters. Refer to /places section for more details. |
Default filters can be specified without the filter name.
The Web services supports several parameters (name/value pairs) called "matrix parameters" that allow users to request small portions of potentially large collections. Matrix parameters follow the collection name or filter they refer to. They are preceded and separated by a semi-colon (";"), and consist of the parameter name, an equals sign ("="), and a numeric or string value. Values may not contain semi-colons, equals signs, or question marks.
The following matrix parameters are supported by the Web service:
| Parameter | Collection | Default | Example | Description |
|---|---|---|---|---|
start
|
|
0
|
start=1
|
Skip first N results |
count
|
|
|
count=5
|
Return a maximum of N results. A count of 0 is interpreted as 'no maximum' (all resources). |
The Web service supports several parameters (name/value pairs) called "query parameters" that allow users to specify a particular language or format for the response. Query parameters follow the resource/collection name, filter, and any matrix parameters. They are preceded by a question mark ("?") and separated by ampersands ("&") and consist of the parameter name, an equals sign ("="), and a numeric or string value. Values may not contain question marks or ampersands.
The following query parameters are supported by the Web service:
| Parameter | Collection | Default | Example | Description |
|---|---|---|---|---|
lang
|
|
(Accept-Language header)
|
lang=fr-CA
|
Return names in specified language (RFC 4646) Overrides language indicated by Accept-Language header |
format
|
all
|
(Accept header)
|
format=json
|
Return results in specified format:
Overrides format indicated by Accept header; required if the request does not include an Accept header |
callback
|
all
|
(none)
|
callback=myfunc
|
Return JSON results wrapped in a JavaScript function call; only used when format=json or format=geojson |
select
|
|
|
select=long
|
Return results in specified representation: short,
long. |
appid
|
all
|
(required)
|
appid=myappid
|
Grants authorization to use the web service; required for all requests |
The Web service supports several HTTP headers that allow users to specify the desired content type and language for the response. These headers may be overridden by query parameters.
The following headers are supported by the Web service: