README
Welcome to Spott. We build tools to make easier for developers to work with geographical places, specifically: cities, countries and administrative divisions (states, regions, provinces, etc). At first, we created Spott to solve our own needs in other projects, then we realized other devs had the same problems and launched it to the world.
With Spott you’ll be able to:
- Search places by a full query or autocompletion, across more than 240,000 records from all the world.
- Filter them by country, type and location.
- Find places and get their localized names in more than 20 languages.
- Get the place where an IP address is located.
We’d love to hear what are you using Spott for, or any idea to make it better.
SDKs
Use our SDKs to make the integration easier:
Authentication
To access Spott you need to do it through RapidAPI. It’s very easy, just:
- Create a RapidAPI account.
- Subscribe to Spott. This will generate an API Key.
- Start making requests. Send your API Key in
X-RapidAPI-Key
header.
More details here.
Data structure
Places
All places returned by Spott might have the following properties.
Property | Type | Description |
---|---|---|
id |
String | Unique identifier given by Spott. |
geonameId |
Integer | Unique identifier given by GeoNames. |
type |
String | The classification of the place. Possible values are: CITY , ADMIN_DIVISION_1 , ADMIN_DIVISION_2 and COUNTRY |
name |
String | Default name of the place (usually in English). This property always has a value. |
localizedName |
String | Localized name of the place in the requested language. This property is only present when parameter language is specified. It’s null when translation is not available. |
population |
Integer | The approximate population living in the place. |
elevation |
Float | The approximate elevation from sea level. Value is expressed in meters. |
coordinates |
Object | The geographic coordinates where the place is located. |
coordinates.latitude |
Float | Latitude component from the geographic coordinates of the place. |
coordinates.longitude |
Float | Longitude component from the geographic coordinates of the place. |
timezoneId |
String | Time zone associated to the place. This property is null for countries since they may have multiple. |
score |
Float | Calculated score used to sort results by relevance. This property is only present in results of endpoints that return a list. |
adminDivision2 |
Object | A minimal version of the Administrative Division level 2 where the place is located. This property is only present for places of type: CITY . The object contain the properties: id , geonameId , name and localizedName . |
adminDivision1 |
Object | A minimal version of the Administrative Division level 1 where the place is located. This property is only present for places of types: CITY and ADMIN_DIVISION_1 . The object contain the properties: id , geonameId , name and localizedName . |
country |
Object | A minimal version of the Country where the place is located. This property is only present for places of types: CITY , ADMIN_DIVISION_1 and ADMIN_DIVISION_2 . The object contain the properties: id , geonameId , name and localizedName . |
Countries
Additionally to Place properties, a place of type COUNTRY
might include the properties:
Property | Type | Description |
---|---|---|
iso2 |
String | ISO 3166-1 Alpha-2 code of the country. |
iso3 |
String | ISO 3166-1 Alpha-3 code of the country. |
isoNumeric |
String | ISO 3166-1 Numeric code of the country. |
continentId |
String | Id of the continent where the country is located. Valids are AF (Africa), AS (Asia), EU (Europe), NA (North America), OC (Oceania), SA (South America) and AN (Antarctica). |
domain |
String | Top-level domain of the country. |
areaSqKm |
Integer | Total area of the country. Expressed in squared kilometers. |
currencyCode |
String | Code of the official currency of the country. |
currencyName |
String | Name of the official currency of the country. |
postalCodeFormat |
String | Format of the postal codes used in the country. |
postalCodeRegex |
String | Regular expression to validate the postal codes used in the country. |
phoneCodes |
Array[String] | A list of the international phone codes to call a number in the country. |
neighbourCountryIds |
Array[String] | A list of ids of the countries that share border with it (neighbours). |
languages |
Array[String] | A list of languages spoken in the country. |
locales |
Array[String] | A list of locales (language + region) used in the country. |
Administrative divisions
All countries have different ways to organize or divide by political entities, and each one may call them differently: States, Provinces, Regions and so on. Since names vary from country to country we call all of them “Administrative Divisions” or “Admin Divisions” to make it shorter.
Administrative Divisions might have their own subdivisions and this may be repeated multiple times (some countries have 5 levels of subdivisions). At Spott you can find only divisions up to level 2, further levels are irrelevant for most applications.
In our data, to reference the first and broadest division level we call it adminDivision1
and their subdivisions are called adminDivision2
.
Having said that, the hierarchy of the places by type is:
COUNTRY
→ ADMIN_DIVISION_1
→ ADMIN_DIVISION_2
* → CITY
⚠️ *Not all countries have admin divisions level 2.
ID or Geoname ID?
All places returned by Spott have properties id
and geonameId
:
id
: Is the unique place identifier given by Spott.geonameId
: Is the unique place identifier given by GeoNames, which is an open geographical database.
Although both ids are great to store and reference places from you app, we recommend to use id
. Because:
- It’s more meaningful.
id
is for places and admin divisions easier to understand and remember.geonameId
is just a number. For example: for “United States”id
is “US” andgeonameId
is “6252001”. - It’s fully supported by Spott. For example, filter parameters are specified with
id
rather thangeonameId
.
*For cities, both id
and geonameId
are the same.
Name and localizedName
Places returned by Spott have ALWAYS the property name
. Which is the most standard name for that place and it’s usually in English.
Additionally, all endpoints support the parameter language
, which if specified will return the property localizedName
with the translation of the place in the requested language.
For example:
GET /places/FR?language=zh
will return name: "France"
and localizedName: "法国"
⚠️ It’s common that we don’t have a translation for a place, most of the times it’s because the translation would be the same than the value in name
. In those cases the property localizedName
will have a null
value. Therefore we strongly recommend that you application fallbacks to name
property.
Languages
Languages are ISO 639-1 codes.
Each place is stored with multiple translations and synonyms, which allows Spott to find places with a wide range of strings, rather than just the official name.
For example you could search for Germany as “Deutschland” (in German), “Federal Republic of Germany” (official name) or “ألمانيا” (in Arabic).
Supported languages
Our database contains place names in more 181 languages however, there are 21 languages with significant support:
ISO 639-1 | ISO Language name |
---|---|
ar |
Arabic |
bg |
Bulgarian |
de |
German |
en |
English |
eo |
Esperanto |
es |
Spanish |
fa |
Persian |
fr |
French |
id |
Indonesian |
it |
Italian |
ja |
Japanese |
kk |
Kazakh |
ko |
Korean |
nl |
Dutch |
pl |
Polish |
pt |
Portuguese |
ru |
Russian |
sr |
Serbian |
uk |
Ukrainian |
ur |
Urdu |
zh |
Chinese |
IP accuracy
You can send an IP v4 or v6 to GET /places/ip/{ip}
endpoint to get the place where the IP is located. Spott will return the most accurate place possible, that means Spott will try to always return a CITY.
However, depending on the ISP there’s no always enough data to calculate the city. In those cases, Spott will return the COUNTRY. You can notice the difference by checking the property type
on the response.
Free plan
Spott offers a Free plan with up to 10,000 requests per month to any endpoint.
Unfortunately RapidAPI will require your credit card details to subscribe to our Free plan; that’s something we can’t change. However, since Free plan is hard limited to 10,000 request, be confident neither Spott or RapidAPI will change anything unless you upgrade to a paid plan.
Data
Our places data is based on GeoNames.org, which is the largest open geographical database.
Help
If you have any comment, question or you want to ask for a feature, feel free to contact us through RapidAPI or our chat in spott.dev.