Teleport public APIs

Getting started

The structure of Teleport APIs is self-describing, e.g. starting at the API root (https://api.teleport.org/api/), the following response is returned (we recommend using the JSONView plugin for Chrome, Safari or Firefox to explore the API):

{
  "_links": {
    "city:list-largest": {
      "href": "https://api.teleport.org/api/cities/"
    },
    "city:search-by-geohash": {
      "href": "https://api.teleport.org/api/cities/{?geohash}",
      "templated": true
    },
    "city:search-by-text": {
      "href": "https://api.teleport.org/api/cities/{?search}",
      "templated": true
    },
    "country:list": {
      "href": "https://api.teleport.org/api/countries/"
    },
    "location:by-coordinates": {
      "href": "https://api.teleport.org/api/locations/{coordinates}/",
      "templated": true
    },
    "self": {
      "href": "https://api.teleport.org/api/"
    },
    "tz:list": {
      "href": "https://api.teleport.org/api/timezones/"
    },
    "ua:list": {
      "href": "https://api.teleport.org/api/urban_areas/"
    }
  }
}

Try it out on our API Explorer

Each resource has a _links element that refers to related resources grouped by relation name. This follows the Hypermedia Application Language draft standard used already by various API providers, e.g. Amazon AWS.

Searching for Cities by Name

You can try a quick example search for San Francisco or use our already implemented autocomplete widget to make sure your users enter existing/real cities:

alt text

You can read more about the widget or access the code on github. And In case you want to dig into the specifics of the city name search:

The root API lists the URL https://api.teleport.org/api/cities/{?search} for the city:search-by-text relation. The curly braces at the end (and the "templated": true attribute) signify parameters according to the URI Template standard (RFC 6570). Let's try to find San Francisco: https://api.teleport.org/api/cities/?search=san%20francisco

{
  "_embedded": {
    "city:search-results": [
      {
        "_links": {
          "city:item": {
            "href": "https://api.teleport.org/api/cities/geonameid:5391959/"
          }
        },
        "matching_alternate_names": [
          {
            "name": "San Francisco"
          }
        ],
        matching_full_name: "San Francisco, California, United States"
      },
      ...
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.teleport.org/api/cities/?search=san francisco"
    }
  },
  "count": 25
}

Try it out on our API Explorer

The response contains an _embedded element with relations similar to what we saw with _links before. The embedded city:search-results relation contains a list of 25 search results. The search results show the matching names of the cities, and refer to the city URL for detailed information about each city via the city:item link relation. Note that if you are using JavaScript or some other language that allows accessing dictionary items using the object member syntax, you have to use use the explicit dictionary item syntax (e.g. response._embedded["city:search-results"]) for the relation names, because the relation names contain the colon (':') character, which is invalid in an identifier.

Basic Information About a City

Once you have the city from the previous section, you might want to check what country or timezone it’s in or how many people live there. This can easily be accomplished with the following example query for San Francisco:

Following the first linked city URL (https://api.teleport.org/api/cities/geonameid:5391959/) we can see details about San Francisco:

{
  "_links": {
    "city:admin1_division": {
      "href": "https://api.teleport.org/api/countries/iso_alpha2:US/admin1_divisions/geonames:CA/"
    },
    "city:country": {
      "href": "https://api.teleport.org/api/countries/iso_alpha2:US/"
    },
    "city:timezone": {
      "href": "https://api.teleport.org/api/timezones/iana:America%2FLos_Angeles/"
    },
    "city:urban_area": {
      "href": "https://api.teleport.org/api/urban_areas/slug:san-francisco-bay-area/"
    },
    "self": {
      "href": "https://api.teleport.org/api/cities/geonameid:5391959/"
    }
  },
  "alternate_names": [
    {
      "name": "Franciscopolis"
    },
    {
      "name": "Frisco"
    },
    ...
  ],
  "geoname_id": 5391959,
  "location": {
    "geohash": "9q8yyk8yuv26emr0cctm",
    "latlon": {
      "latitude": 37.77493,
      "longitude": -122.41942
    }
  },
  "name": "San Francisco",
  "population": 805235
}

Try it out on our API Explorer

The city resource again refers to several linked resources (country, administrative division/state, timezone, Teleport Startup City).

As you can see there’s plenty of useful information returned and for cities that are also part of Teleport urban areas, we can provide much more engaging content.

Income, Living Costs & Quality of Life Data

Teleport aggregates its data sources and computes scores for urban areas (Teleport Cities) across various different categories. Currently our API provides scores for housing, cost of living, startups, venture capital, travel connectivity, commute, business freedom, safety, healthcare, education, environmental quality, economy, taxation and internet access. Our partners like Human have implemented some cool visuals based on top of our API:

alt text

For example, you can tease this information out for San Francisco Bay Area with the following request: (https://api.teleport.org/api/urban_areas/slug:san-francisco-bay-area/scores/)

{
  "_links": {
    "curies": [
      {
        "href": "https://developers.teleport.org/api/",
        "name": "location"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "city"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "ua"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "country"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "a1"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "tz"
      }
    ]
  },
  "categories": [
    {
      "color": "#0051C1",
      "name": "Housing",
      "score_out_of_10": 0.9999999999999999
    },
    {
      "color": "#0084F3",
      "name": "Cost of Living",
      "score_out_of_10": 2.8529999999999998
    },
    {
      "color": "#00BDF3",
      "name": "Startups",
      "score_out_of_10": 10
    },
    {
      "color": "#00E3DF",
      "name": "Venture Capital",
      "score_out_of_10": 10
    },
    {
      "color": "#006C02",
      "name": "Travel Connectivity",
      "score_out_of_10": 7.342999999999998
    },
    {
      "color": "#009E00",
      "name": "Commute",
      "score_out_of_10": 5.1885
    },
    {
      "color": "#8BC00C",
      "name": "Business Freedom",
      "score_out_of_10": 8.338000000000001
    },
    {
      "color": "#CB5947",
      "name": "Safety",
      "score_out_of_10": 4.902
    },
    {
      "color": "#D92500",
      "name": "Healthcare",
      "score_out_of_10": 6.7349999999999985
    },
    {
      "color": "#B1005E",
      "name": "Education",
      "score_out_of_10": 7.560499999999999
    },
    {
      "color": "#B05F95",
      "name": "Environmental Quality",
      "score_out_of_10": 5.9485
    },
    {
      "color": "#7A1F7A",
      "name": "Economy",
      "score_out_of_10": 6.898999999999999
    },
    {
      "color": "#46247F",
      "name": "Taxation",
      "score_out_of_10": 3.2039999999999997
    },
    {
      "color": "#6929C1",
      "name": "Internet Access",
      "score_out_of_10": 5.688
    }
  ],
  "summary": "<p>\n    San Francisco Bay Area is among the best cities with a <b>vibrant startup scene</b>\n\n    \n        In general, this city has very good ratings in <b>Venture Capital</b>, <b>Travel Connectivity</b> and <b>Business Freedom</b>.\n    \n\n    \n        On the other hand, this city is not a good place for <b>Housing</b>, <b>Cost of Living</b> and <b>Taxation</b>.\n    \n\n</p>\n\n    <p>San Francisco Bay Area is one of the top ten city matches for 25.6% of Teleport users.</p>\n",
  "teleport_city_score": 65.34964285714285
}

Alternatively, we can find the Urban Area that a city belongs to. E.g. let's find out how the urban area corresponding to Palo Alto, California performs in terms of Teleport scores. Let's use the API Explorer for the city search endpoint to construct the URL. In the search field enter Palo Alto, California, in the embed field, type city:search-results/city:item/city:urban_area/ua:scores, and click the Try it out! button.

The API Explorer should give the following URL: https://api.teleport.org/apicities/?search=Palo%20Alto%2C%20California&embed=city%3Asearch-results%2Fcity%3Aitem%2Fcity%3Aurbanarea%2Fua%3Ascores and the corresponding API response:

{
  "_embedded": {
    "city:search-results": [
      {
        "_embedded": {
          "city:item": {
            "_embedded": {
              "city:urban_area": {
                "_embedded": {
                  "ua:scores": {
                    "categories": [
                      {
                        "color": "#0051C1",
                        "name": "Housing",
                        "score_out_of_10": 0.9999999999999999
                      },
                      {
                        "color": "#0084F3",
                        "name": "Cost of Living",
                        "score_out_of_10": 2.8529999999999998
                      },
                      // ...
                      {
                        "color": "#6929C1",
                        "name": "Internet Access",
                        "score_out_of_10": 5.688
                      }
                    ],
                    "summary": "Among the best attributes of San Francisco Bay Area, you can count on a <b>buoyant economy</b>. In general, this city has very good ratings in <b>Startups</b>, <b>Venture Capital</b>, <b>Travel Connectivity</b>, <b>Business Freedom</b>, <b>Healthcare</b> and <b>Education</b>. At the same time, it has low ratings in <b>Housing</b>, <b>Cost of Living</b> and <b>Taxation</b>. <br/><br/>San Francisco Bay Area is one of the top ten city matches for 25.6% of Teleport users.",
                    "teleport_city_score": 65.34964285714285
                  }
                },
                "_links": { ... },
                "name": "San Francisco Bay Area",
                "teleport_city_url": "https://teleport.org/cities/san-francisco-bay-area/",
                "ua_id": "9q8yy"
              }
            },
            ...
            "geoname_id": 5380748,
            "location": {
              "geohash": "9q9jh844v274h2gte8sk",
              "latlon": {
                "latitude": 37.44188,
                "longitude": -122.14302
              }
            },
            "name": "Palo Alto",
            "population": 64403
          }
        },
        ...
        "matching_full_name": "Palo Alto, California, United States"
      }
    ]
  },
  "count": 1
}

The response is pretty deep, but if you ignore the alternating _embedded fields (which are part of the HAL standard), the hierarchy should make sense:

  • city:search-results (the textual search results, including the full name that was used for the textual match)
  • city:item (the city details - Palo Alto)
  • city:urban_area (the urban area that the city belongs to - San Francisco Bay Area)
  • ua:scores (the Teleport City Scores for San Francisco Bay Area)

The scores resource shows a textual summary using limited HTML markup, e.g. from the above:

Among the best attributes of San Francisco Bay Area, you can count on a buoyant economy. In general, this city has very good ratings in Startups, Venture Capital, Travel Connectivity, Business Freedom, Healthcare and Education. At the same time, it has low ratings in Housing, Cost of Living and Taxation.

San Francisco Bay Area is one of the top ten city matches for 25.6% of Teleport users.

It also shows an aggregate Teleport City Score (65 out of 100 for San Francisco Bay Area).

And finally, there is a breakdown into individual categories that the cities are evaluated for (e.g. Housing, Cost of Living). For each category, the city is assigned a score on a scale from 0 to 10. The response also includes the colors for the categories that match the colors of the bars that Teleport products use for showing the scores.

Photos for Urban Areas

If you’re running a site that provides content about various cities and want to lighten it up with city images without having to go through the pain of finding them, then you’re in luck. We’ve already went through that pain and found a good set of images you can freely use (without getting sued).

You can get the list of urban areas we have images for with this request: (https://api.teleport.org/api/urban_areas)

and plug the teleport id into the following URL to get both a mobile and web image urls for Paris for example: (https://api.teleport.org/api/urban_areas/slug:san-francisco-bay-area/images/)

{
  "_links": {
    "curies": [
      {
        "href": "https://developers.teleport.org/api/",
        "name": "location"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "city"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "ua"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "country"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "a1"
      },
      {
        "href": "https://developers.teleport.org/api/",
        "name": "tz"
      }
    ]
  },
  "photos": [
    {
      "attribution": {
        "license": "Attribution, ShareAlike",
        "photographer": "Lucas Theis",
        "site": "Unsplash",
        "source": "https://unsplash.com/lucastheis"
      },
      "image": {
        "mobile": "https://d13k13wj6adfdf.cloudfront.net/urban_areas/San_Francisco_9q8yy-68f5c7173b.jpg",
        "web": "https://d13k13wj6adfdf.cloudfront.net/urban_areas/San_Francisco_9q8yy_web-9a4042d87e@3x.jpg"
      }
    }
  ]
}

or why not get urls to all images of our urban areas by embedding it all into a single request: (https://api.teleport.org/api/urban_areas/?embed=ua:item/ua:images)

Embedding Linked Resources

Following all these links in a client application is probably not all that convenient. So the Teleport APIs support an embed query string parameter, with which it is possible to "pre-fetch" or embed linked resources into parent resources. The embed parameter takes relation names as values, with child relations separated from parents with a slash, e.g. city:search-results/city:item, as in: https://api.teleport.org/api/cities/?search=san%20francisco&embed=city%3Asearch-results%2Fcity%3Aitem

{
  "_embedded": {
    "city:search-results": [
      {
        "_embedded": {
          "city:item": {
            "_links": {
              "city:admin1_division": {
                "href": "https://api.teleport.org/api/countries/iso_alpha2:US/admin1_divisions/geonames:CA/"
              },
              "city:country": {
                "href": "https://api.teleport.org/api/countries/iso_alpha2:US/"
              },
              "city:timezone": {
                "href": "https://api.teleport.org/api/timezones/iana:America%2FLos_Angeles/"
              },
              "city:urban_area": {
                "href": "https://api.teleport.org/api/urban_areas/slug:san-francisco-bay-area/"
              },
              "self": {
                "href": "https://api.teleport.org/api/cities/geonameid:5391959/"
              }
            },
            "alternate_names": [
              {
                "name": "Franciscopolis"
              },
              {
                "name": "Frisco"
              },
              ...
            ],
            "geoname_id": 5391959,
            "location": {
              "geohash": "9q8yyk8yuv26emr0cctm",
              "latlon": {
                "latitude": 37.77493,
                "longitude": -122.41942
              }
            },
            "name": "San Francisco",
            "population": 805235
          }
        },
        "_links": {
          "city:item": {
            "href": "https://api.teleport.org/api/cities/geonameid:5391959/"
          }
        },
        "matching_alternate_names": [
          {
            "name": "San Francisco"
          }
        ]
      },
      ...
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.teleport.org/api/cities/?search=san francisco"
    }
  },
  "count": 25
}

Now the city details are available directly in the search results via the object path _embedded/city:search-results[0]/_embedded/city:item.

Multiple embed paths can be specified by repeating the embed parameter in the URL: embed=city:search-results/city:item/city:country&embed=city:search-results/city:item/city:admin1_division&embed=city:search-results/city:item/city:urban_area&embed=city:search-results/city:item/city:timezone/tz:offsets-now

Alternatively, embed paths can be specified using a hierarchical syntax, where children of a common prefix can be specified in curly braces, separated by comma, e.g. embed=city:search-results/city:item/{city:country,city:admin1_division,city:urban_area,city:timezone/tz:offsets-now}

Searching for Nearest Cities

If the coordinates for a location (e.g. mobile phone GPS coordinates) are known and you need to find the nearest city, the location API (location:by-coordinates relation from root). Provide the latitude and longitude in the coordinates parameter, e.g. 37.77493,-122.41942: https://api.teleport.org/api/locations/37.77493,-122.41942/

{
  "_embedded": {
    "location:nearest-cities": [
      {
        "_links": {
          "location:nearest-city": {
            "href": "https://api.teleport.org/api/cities/geonameid:5391959/"
          }
        }
      }
    ],
    "location:nearest-urban-areas": [
      {
        "_links": {
          "location:nearest-urban-area": {
            "href": "https://api.teleport.org/api/urban_areas/slug:san-francisco-bay-area/"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.teleport.org/api/locations/37.774930,-122.419420/"
    }
  },
  "coordinates": {
    "latlon": {
      "latitude": 37.77493,
      "longitude": -122.41942
    }
  }
}

Try it out on our API Explorer

City detail data can be embedded in a similar manner as in the search-by-text scenario above using the embed parameter (notice how each resource has their own relations): https://api.teleport.org/api/locations/37.77493,-122.41942/?embed=location%3Anearest-cities%2Flocation%3Anearest-city