Subnational2Code List and Search Web Service API
API
This functionality is contained in the IS/DataDeliveryREST code base.
URL |
description |
status |
notes |
|---|---|---|---|
ws/ref/subnational2/list?countryCode=<2-letter ISO country code> |
Return list of "county" names found in the given country |
coded, not deployed |
|
ws/ref/subnational2/find?match=<string to match> |
Return list of "county" names that match |
coded, not deployed |
Can wildcards be used in the match string? No wildcard yet implemented. |
ws/ref/subnational2/list?subnational1Code=<subnational1 code> |
Return list of "county" names found in the given "state" |
coded, not deployed |
|
parameter |
required |
default |
value options |
description |
status |
|---|---|---|---|---|---|
match |
yes, for /find |
n/a |
|
String to match against "county" names. What kind of wildcards can be used? |
coded, not deployed. No wildcard yet implemented. |
locale |
no |
en_US |
Java standard locale codes |
locale in which to perform matching, and in which to provide names in response (when possible) |
not coded |
countryCode |
one of countryCode and subnational1Code is required for /list |
n/a |
|
see CountryCode List and Search Web Service API |
coded, not deployed |
subnational1Code |
one of countryCode and subnational1Code is required for /list |
n/a |
|
coded, not deployed |
|
format |
no |
csv |
|
format to use for response |
coded, not deployed |
Test URLS
Development URL |
Deployed URL |
Expected Response |
Notes |
|---|---|---|---|
|
empty list in CSV format |
|
|
|
empty list in CSV format |
|
|
|
entire list in CSV format |
Country code in uppercase is valid. |
|
|
empty list in CSV format |
Country code in lowercase is invalid. |
|
http://localhost/ws/ref/subnational2/list?countryCode=US&format=xml |
|
entire list in XML format |
|
http://localhost/ws/ref/subnational2/list?countryCode=US&format=csv |
|
entire list in CSV format |
|
http://localhost/ws/ref/subnational2/list?countryCode=US&format=XML |
|
entire list in CSV format |
"XML" is not a valid format option. Only "xml" and "csv" are valid options. |
http://localhost/ws/ref/subnational2/list?countryCode=US&format= |
|
entire list in CSV format |
Bad format value is ignored and defaulted to csv. |
http://localhost/ws/ref/subnational2/list?countryCode=US&format=QQQ |
|
entire list in CSV format |
Bad format value is ignored and defaulted to csv. |
|
empty list in CSV format |
|
|
http://localhost/ws/ref/subnational2/list?subnational1Code=US-NY |
|
entire list in CSV format |
Subnational1 code in uppercase is valid. |
http://localhost/ws/ref/subnational2/list?subnational1Code=us-ny |
|
empty list in CSV format |
Subnational1 code in lowercase is invalid. |
http://localhost/ws/ref/subnational2/list?subnational1Code=US-NY&format=xml |
|
entire list in XML format |
|
|
entire list in CSV format |
|
|
|
entire list in CSV format |
There should be no difference in response for upper/lower case search strings. |
|
http://localhost/ws/ref/subnational2/find?match=clay&format=xml |
|
entire list in XML format |
|
|
empty list in CSV format |
|
CSV Result Format
<country code>, <subnational1 code>, <subnational2 code>, <name associated with subnational2 code>
<country code>, <subnational1 code>, <subnational2 code>, <name associated with subnational2 code
<country code>, <subnational1 code>, <subnational2 code>, <name associated with subnational2 code>
XML Result Format
<response>
<header>
<locale country="US" language="en"/>
<timestamp>2008-02-21T12:37:32.546-05:00</timestamp>
<criteria>
<property name="match" value="seomthing"/>
<property name="subnational1Code" value="seomthing"/>
<property name="countryCode" value="seomthing"/>
</criteria>
<comment>
</comment>
</header>
<result>
<location countryCode="" subnational1Code="" subnational2Code="">name of the subnational2 region </location>
<location countryCode="" subnational1Code="" subnational2Code="">name of the subnational2 region </location>
<location countryCode="" subnational1Code="" subnational2Code="">name of the subnational2 region </location>
<location countryCode="" subnational1Code="" subnational2Code="">name of the subnational2 region </location>
</result>
</response>