CountryCode List and Search Web Service API

API

URL

description

status

notes

ws/ref/country/list

Return entire list of country names and codes

deployed

 

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

Return list of country names and their codes that match

deployed

What 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 "country" 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

format

no

csv

  • csv
  • xml

format to use for response

deployed

Test URLS

Development URL

Deployed URL

Expected Response

Notes

http://localhost/ws/ref/country

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

entire list in CSV format

Generates 404

http://localhost/ws/ref/country/list

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

entire list in CSV format

"csv" is the default format.

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

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

entire list in XML format

 

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

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

entire list in CSV format

 

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

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

entire list in CSV format

Bad format value is ignored and defaulted to csv.

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

http://ebird.org/ws1.0/ref/country/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/country/find?match=united

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

list of countries in CSV format

 

http://localhost/ws/ref/country/find?match=united&format=xml

http://ebird.org/ws1.0/ref/country/find?match=united&format=xml

XML list of countries

 

http://localhost/ws/ref/country/find?match=UNITED

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

list of countries in CSV format

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

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

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

entire list in CSV format

Bad format value is ignored and defaulted to csv.

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

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

empty list in CSV format

 

CSV Result Format

<country code>, <name associated with country code>
<country code>, <name associated with country code>
<country code>, <name associated with country 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="something"/>
    </criteria>
    <comment>
    </comment>
  </header>
  <result>
    <location countryCode="" >name of the country </location>
    <location countryCode="" >name of the country </location>
    <location countryCode="" >name of the country </location>
</response>
  • No labels

2 Comments

  1. Anonymous

    This comment refers to many CSV URL's I have experimented with.

    As an example, when I load this example URL given above:

    http://www.avianknowledge.net/ws1.0/ref/country/list

    the first first lines returned look like this ...

    AF,
    Afghanistan
    AL,
    Albania
    DZ,
    Algeria
    AS,
    American Samoa
    AD,
    Andorra

    According to add definitions of CSV that I have seen, all the columns making up a row should be on the same line. One could see how to convert this file into a conventional CSV file by joining all lines that end with a comma, but shouldn't have to be done. Is there something else in here that I don't understand?

    Tom Wetmore

    1. Paul Allen

      Thanks for letting us know about this problem. We will address is as soon as we can.