*** This version of Confluence is for testing only and contains a copy of content from June 29th 2026. No changes will be preserved. ***
| Panel | |
|---|---|
|
Subnational1Code List and Search Web Service API
API
This is implemented in the IS/DataDeliveryREST code base.
URL | description | status | notes |
|---|---|---|---|
ws/ref/subnational1/list | Return entire list of "state" names | coded, not deployed |
|
ws/ref/subnational1/list?countryCode=<2-letter ISO country code> | Return list of "state" names found in the given country | coded, not deployed |
|
ws/ref/subnational1/find?match=<string to match> | Return list of "state" names that match | coded, not deployed | Can wildcards be used in the match string? No wildcard yet implemented. |
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 | no | n/a | 2-letter ISO country code | coded, not deployed | |
format | no | csv |
| format to use for response | coded, not deployed |
Test URLS
Development URL | Deployed URL | Expected Response | Notes | |
|---|---|---|---|---|
entire list in CSV format | Generates 404 error. | |||
http://localhost What do we want here? 404? Redirect to /ws/ref/subnational1/list? | http://localhost/wsebird.org/ws1.0/ref/subnational1/list |
| entire list in CSV format | "csv" is the default format. |
entire list in XML format |
| |||
entire list in CSV format |
| |||
entire list in CSV format | Bad format value is ignored and defaulted to csv. | |||
entire list in CSV format | "XML" is not a valid format option. Only "xml" and "csv" are valid options. | |||
CSV list of states | Country code string in uppercase is valid. | |||
http://localhost/ws/ref/subnational1/list?countryCode=US&format=xml | http://ebird.org/ws1.0/ref/subnational1/list?countryCode=US&format=xml | XML list of states |
| |
empty list in CSV format | Country code string in lowercase is invalid. | |||
entire list in CSV format |
| |||
list of states in CSV format |
| |||
http://localhost/ws/ref/subnational1/find?match=new&format=xml | http://ebird.org/ws1.0/ref/subnational1/find?match=new&format=xml | list of states in XML format |
| |
list of states in CSV format | There should be no difference in response for upper/lower case search strings. | |||
entire list in CSV format | Bad format value is ignored and defaulted to csv. | |||
empty list in CSV format |
|
CSV Result Format
| Panel |
|---|
<country code>, <subnational1 code>, <name associated with subnational1 code> |
XML Result Format
| No 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="countryCode" value="US" description="United States"/>
</criteria>
<comment>
</comment>
</header>
<result>
<location countryCode="" subnational1Code="">name of the subnational1 region </location>
<location countryCode="" subnational1Code="">name of the subnational1 region </location>
<location countryCode="" subnational1Code="">name of the subnational1 region </location>
<location countryCode="" subnational1Code="">name of the subnational1 region </location>
</result>
</response>
|