Language & Location Reference
Some Instant Answers employ contextual data about the user's search to provide the most relevant results. For example, since sunrise and sunset times vary widely around the world, the sunrise/sunset Instant Answer requires the user's approximate location.
The core DDG library provides Goodie and Spice Instant Answers with location and language APIs to provide simple, helpful and delightful results.
The core DDG library provides a Location API. Since Goodie and Spice Instant Answers inherit from this package, their
handle functions have access to a
$loc variable which refers to a Location object.
This Location object has a number of useful attributes to help you provide relevant answers:
my @geo_ip_record_attrs = qw( country_code country_code3 country_name region region_name city postal_code latitude longitude time_zone area_code continent_code metro_code );
Example data from
country_code => US country_code3 => USA country_name => United States region => PA region_name => Pennsylvania city => Phoenixville postal_code => 19460 latitude => 40.1246 longitude => -75.5385 time_zone => America/New_York area_code => 610 continent_code => NA metro_code => 504
Note: When testing Instant Answers interactively with
duckpan, the location will always point to "Phoenixville, Pennsylvania, United States":
my $location = join(", ", $loc->city, $loc->region_name, $loc->country_name); # "Phoenixville, Pennsylvania, United States"
For assistance with specifying the location to be used in automated testing, please refer to the Location API testing guide.
Naturally, once your Instant Answer is live,
$loc will refer to the appropriate location.
The core DDG library exposes a Language API which Goodie and Spice Instant Answers can access in their
handle functions. The language data is contained in the
$lang refers to a Language object with the following properties:
my @language_attributes = qw( flagicon flag_url name_in_local rtl locale nplurals name_in_english);
Example data from
'nplurals' => 2, 'name_in_local' => 'English of United States', 'rtl' => 0, 'flag_url' => 'https://duckduckgo.com/f2/us.png', 'name_in_english' => 'English of United States', 'locale' => 'en_US', 'flagicon' => 'us'
Note: The user's locale does not imply their preferred language. It simply provides the locale based on the user's IP. Thus, the locale should not be used to determine the display language for an Instant Answer.
When testing interactively with
duckpan, the locale will always be set to
It is possible to set different locales when running automated tests. Please refer to the Language API testing guide for more information.