Documentation

Using the Cities API is as simple as making an HTTP request.

There is only one step: submit the URL that fits your needs. That is it!

If this sounds good, then take a few minutes to read about more details.

The API is currently in beta.

There are imperfections, especially in the translations.

You can help make it better by reporting bugs or suggesting translations.

URL Structure

First, let's take a look at what a typical URL request for the API would look like:

http://cities.shopgo.io/api/countries?username=test&limit=2&term=ang

This can be split into three parts:

  1. The stemhttp://cities.shopgo.io/api/, which is the path to access the API. https is also supported.

  2. What you are looking forcountries, the other option cities.

  3. Additional parameters?username=test&limit=2&term=ang, used to ensure that you get the results you are looking for.

Parameters

Additional parameters take the form of a query string attached to the end of the URL path.

Reminder: A query string is indicated by a ? and lists key-value pairs in the form key=value, separated by an &. The order of these pairs does not make a difference.

Below is a list of available parameters:

  • username

    • Description — Username of a registered user
    • Values — A valid username
    • Default — N/A
    • Required
  • format

    • Description — Data format of results
    • Valuesjson, xml
    • Defaultjson
    • Optional
  • limit

    • Description — Maximum number of results
    • Values0 (no limit), Positive integer
    • Default0
    • Optional
  • term

    • Description — Search term
    • Values — String
    • Default — N/A
    • Optional
  • lang

    • Description — Language of the parameter term or the language to sort results by if no term is specified
    • Valuesen, ar, auto
    • Defaultauto
    • Optional
  • country

    • Description — Two-character country code
    • ValuesISO 3166-1 alpha-2
    • Default — N/A
    • Required for cities

Keep in mind that city lists are currently available for Arabic-speaking countries only, which are: 'AE', 'BH', 'DJ', 'DZ', 'EG', 'IQ', 'JO', 'KW', 'LB', 'LY', 'MA', 'MR', 'OM', 'PS', 'QA', 'SA', 'SD', 'SO', 'SY', 'TN', 'YE'.

Notes on parameters

  • Parameter values should not be surrounded with quotes in the URL.
  • Parameter values are case-insensitive.
  • Parameter order has no effect on the results.

Results

Regardless of the format you choose for the results, the structure is simple and clean. Take a look for yourself!

  • JSON

      {
       "count": 2,
        "data" : [
                 {
                  "countryCode":"AO",
                  "en":"Angola",
                  "ar":"أنغولا",
                  "auto":"Angola",
                  "level":"country"
                 },
                 {
                  "countryCode":"AI",
                  "en":"Anguilla",
                  "ar":"أنغويلا",
                  "auto":"Anguilla",
                  "level":"country"
                 }
                  ]
      }
    
  • XML

      <results>
          <count>2</count>
          <data>
              <item>
                  <countryCode>AO</countryCode>
                  <en>Angola</en>
                  <ar>أنغولا</ar>
                  <auto>Angola</auto>
                  <level>country</level>
              </item>
              <item>
                  <countryCode>AI</countryCode>
                  <en>Anguilla</en>
                  <ar>أنغويلا</ar>
                  <auto>Anguilla</auto>
                  <level>country</level>
              </item>
          </data>
      </results>
    

The auto field contains the name in the language which was used to match it with the search term when provided. This is especially useful when no language is specified in the request. For autocomplete purposes, you will most likely want to use this field instead of en or ar.

Examples

To make things even clearer, here are some more examples:

  • To get all countries (JSON):

      http://cities.shopgo.io/api/countries?username=test
    
  • To get all cities in Egypt (JSON):

      http://cities.shopgo.io/api/cities?username=test&country=EG
    

    Remember that with cities you need to specify a country.

  • To get the first 10 cities in Tunisia from the country's complete, English-sorted list (XML):

      http://cities.shopgo.io/api/cities?username=test&limit=10&format=xml&lang=en&country=TN
    
  • To get the top 3 matches for a city in Lebanon corresponding to the Arabic term بييرؤت (XML):

      http://cities.shopgo.io/api/cities?username=test&limit=3&country=LB&format=xml&lang=ar&term=بييرؤت
    

    Keep in mind that the spelling error will be ignored and the top result will be بيروت.

  • To get all matches for the term ]lar in Syria (JSON):

      http://cities.shopgo.io/api/cities?username=test&country=SY&term=]lar
    

    ]lar maps to دمشق when the keyboard input language is set to Arabic. Look at your keyboard!

What now?

Now that you know how to access the API, you can use the results to populate a dropdown list or an autocomplete text field, or use them in any other creative way you can think of!

Sign up and start using Cities right away!