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:
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:
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