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

deployed

 

ws/ref/subnational1/list?countryCode=<2-letter ISO country code>

Return list of "state" names found in the given country

deployed

 

ws/ref/subnational1/find?match=<string to match>

Return list of "state" names that match

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?

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

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/subnational1

http://ebird.org/ws1.0/ref/subnational1

entire list in CSV format

Generates 404 error.

http://localhost/ws/ref/subnational1/list

http://ebird.org/ws1.0/ref/subnational1/list

entire list in CSV format

"csv" is the default format.

http://localhost/ws/ref/subnational1/list?format=xml

http://ebird.org/ws1.0/ref/subnational1/list?format=xml

entire list in XML format

 

http://localhost/ws/ref/subnational1/list?format=csv

http://ebird.org/ws1.0/ref/subnational1/list?format=csv

entire list in CSV format

 

http://localhost/ws/ref/subnational1/list?format=QQQ

http://ebird.org/ws1.0/ref/subnational1/list?format=QQQ

entire list in CSV format

Bad format value is ignored and defaulted to csv.

http://localhost/ws/ref/subnational1/list?format=XML

http://ebird.org/ws1.0/ref/subnational1/list?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/subnational1/list?countryCode=US

http://ebird.org/ws1.0/ref/subnational1/list?countryCode=US

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

 

http://localhost/ws/ref/subnational1/list?countryCode=us

http://ebird.org/ws1.0/ref/subnational1/list?countryCode=us

empty list in CSV format

Country code string in lowercase is invalid.

http://localhost/ws/ref/subnational1/list?countryCode=

http://ebird.org/ws1.0/ref/subnational1/list?countryCode=

entire list in CSV format

 

http://localhost/ws/ref/subnational1/find?match=new

http://ebird.org/ws1.0/ref/subnational1/find?match=new

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

 

http://localhost/ws/ref/subnational1/find?match=NEW

http://ebird.org/ws1.0/ref/subnational1/find?match=NEW

list of states in CSV format

There should be no difference in response for upper/lower case search strings.

http://localhost/ws/ref/subnational1/list?format=

http://ebird.org/ws1.0/ref/subnational1/list?format=

entire list in CSV format

Bad format value is ignored and defaulted to csv.

http://localhost/ws/ref/subnational1/find?match=

http://ebird.org/ws1.0/ref/subnational1/find?match=

empty list in CSV format

 


CSV Result Format

<country code>, <subnational1 code>, <name associated with subnational1 code>
<country code>, <subnational1 code>, <name associated with subnational1 code
<country code>, <subnational1 code>, <name associated with subnational1 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="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>
  • No labels