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	deployed
ws/ref/subnational2/find?match=<string to match>	Return list of "county" names that match	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"	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?	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	deployed
subnational1Code	one of countryCode and subnational1Code is required for /list	n/a		see AKN-1.0-Subnational1	deployed
format	no	csv	csv xml	format to use for response	deployed

Test URLS

Development URL	Deployed URL	Expected Response	Notes
http://localhost/ws/ref/subnational2	http://ebird.org/ws1.0/ref/subnational2	empty list in CSV format	Generates 404 error.
http://localhost/ws/ref/subnational2/list?countryCode=	http://ebird.org/ws1.0/ref/subnational2/list?countryCode=	empty list in CSV format
http://localhost/ws/ref/subnational2/list?countryCode=US	http://ebird.org/ws1.0/ref/subnational2/list?countryCode=US	entire list in CSV format	Country code in uppercase is valid.
http://localhost/ws/ref/subnational2/list?countryCode=us	http://ebird.org/ws1.0/ref/subnational2/list?countryCode=us	empty list in CSV format	Country code in lowercase is invalid.
http://localhost/ws/ref/subnational2/list?countryCode=US&format=xml	http://ebird.org/ws1.0/ref/subnational2/list?countryCode=US&format=xml	entire list in XML format
http://localhost/ws/ref/subnational2/list?countryCode=US&format=csv	http://ebird.org/ws1.0/ref/subnational2/list?countryCode=US&format=csv	entire list in CSV format
http://localhost/ws/ref/subnational2/list?countryCode=US&format=XML	http://ebird.org/ws1.0/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=	http://ebird.org/ws1.0/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	http://ebird.org/ws1.0/ref/subnational2/list?countryCode=US&format=QQQ	entire list in CSV format	Bad format value is ignored and defaulted to csv.
http://localhost/ws/ref/subnational2/list?subnational1Code=	http://ebird.org/ws1.0/ref/subnational2/list?subnational1Code=	empty list in CSV format
http://localhost/ws/ref/subnational2/list?subnational1Code=US-NY	http://ebird.org/ws1.0/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	http://ebird.org/ws1.0/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	http://ebird.org/ws1.0/ref/subnational2/list?subnational1Code=US-NY&format=xml	entire list in XML format
http://localhost/ws/ref/subnational2/find?match=clay	http://ebird.org/ws1.0/ref/subnational2/find?match=clay	entire list in CSV format
http://localhost/ws/ref/subnational2/find?match=CLAY	http://ebird.org/ws1.0/ref/subnational2/find?match=CLAY	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	http://ebird.org/ws1.0/ref/subnational2/find?match=clay&format=xml	entire list in XML format
http://localhost/ws/ref/subnational2/find?match=	http://ebird.org/ws1.0/ref/subnational2/find?match=	empty list in CSV format

CSV Result Format

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>