swagger: "2.0" schemes: - https host: wft-geo-db.p.rapidapi.com basePath: /v1 info: description: | The GeoDB API focuses on getting global city and region data. Easily obtain country, region, and city data for use in your apps!

Notes:


Useful Resources

license: name: Creative Commons Attribution 3.0 url: http://creativecommons.org/licenses/by/3.0/ title: GeoDB Cities API version: 1.0.0 x-apisguru-categories: - developer_tools - location x-logo: backgroundColor: "#FFFFFF" url: https://api.apis.guru/v2/cache/logo/https_wirefreethought.github.io_geodb-cities-api-docs_images_logo.png x-origin: - format: swagger url: https://wirefreethought.github.io/geodb-cities-api-docs/swagger.json version: "2.0" x-providerName: mashape.com x-serviceName: geodb produces: - application/json securityDefinitions: UserSecurity: in: header name: x-rapidapi-key type: apiKey security: - UserSecurity: [] parameters: path.cityId: description: A city id (either native 'id' or 'wikiDataId') in: path name: cityId required: true type: string path.countryId: description: An ISO-3166 country code or WikiData id in: path name: countryId required: true type: string path.divisionId: description: An admin-division id (either native 'id' or 'wikiDataId') in: path name: divisionId required: true type: string path.location.id: description: "A latitude/longitude in ISO-6709 format: ±DD.DDDD±DDD.DDDD" in: path name: locationId required: true type: string path.regionCode: description: An ISO-3166 or FIPS region code in: path name: regionCode required: true type: string path.zoneId: description: A time-zone id in: path name: zoneId required: true type: string query.asciiMode: default: false description: Display results using ASCII characters in: query name: asciiMode required: false type: boolean query.country.currencyCode: description: Only countries supporting this currency in: query name: currencyCode required: false type: string query.country.sort: description: |- How to sort countries. Format: ±SORT_FIELD where SORT_FIELD = code | name in: query name: sort required: false type: string query.currency.countryId: description: Currencies for this country id in: query name: countryId required: true type: string query.distanceUnit: default: MI description: "The unit of distance: MI | KM" in: query name: distanceUnit required: false type: string query.entity.namePrefix: description: | Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language. in: query name: namePrefix required: false type: string query.entity.namePrefixDefaultLangResults: default: true description: | When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set. in: query name: namePrefixDefaultLangResults required: false type: boolean query.hateoasMode: default: true description: Include HATEOAS-style links in results in: query name: hateoasMode required: false type: boolean query.includeDeleted: default: NONE description: "Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE" in: query name: includeDeleted required: false type: string query.languageCode: description: Display results in this language in: query name: languageCode required: false type: string query.limit: default: 10 description: The maximum number of results to retrieve format: int32 in: query name: limit required: false type: integer query.offset: default: 0 description: The zero-ary offset index into the results format: int32 in: query name: offset required: false type: integer query.place.countryIds: description: Only places in these countries (comma-delimited country codes or WikiData ids) in: query name: countryIds required: false type: string query.place.excludedCountryIds: description: Only places NOT in these countries (comma-delimited country codes or WikiData ids) in: query name: excludedCountryIds required: false type: string query.place.location.id: description: "Only places near this location. Latitude/longitude in ISO-6709 format: ±DD.DDDD±DDD.DDDD" in: query name: location required: false type: string query.place.location.radiusOf: description: The location radius within which to find places format: int32 in: query name: radius required: false type: integer query.place.maxPopulation: description: Only places having no more than this population format: int32 in: query name: maxPopulation required: false type: integer query.place.minPopulation: description: Only places having at least this population format: int32 in: query name: minPopulation required: false type: integer query.place.sort: description: | How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population in: query name: sort required: false type: string query.place.sort.withinRegion: description: | How to sort place results. 'Format: ±SORT_FIELD,±SORT_FIELD' where SORT_FIELD = elevation | name | population in: query name: sort required: false type: string query.place.types: description: "Only places for these types (comma-delimited): CITY | ADM2" in: query name: types required: false type: string query.region.sort: description: |- How to sort regions. Format: ±SORT_FIELD where SORT_FIELD = fipsCode | isoCode | name in: query name: sort required: false type: string query.sort: description: | How to sort place results. 'Format: ±SORT_FIELD,±SORT_FIELD' where SORT_FIELD = countryCode | elevation | name | population in: query name: sort required: false type: string query.timeZoneIds: description: Only places in these time-zones (comma-delimited) in: query name: timeZoneIds required: false type: string query.toCityId: description: Distance to this city in: query name: toCityId required: true type: string responses: BadRequest: description: 400 - Bad Request schema: $ref: "#/definitions/BadRequestResponse" Countries: description: A list of countries schema: $ref: "#/definitions/CountriesResponse" Country: description: Country detail schema: $ref: "#/definitions/CountryResponse" Currencies: description: A list of currencies schema: $ref: "#/definitions/CurrenciesResponse" DateTime: description: An ISO-6801 date-time schema: $ref: "#/definitions/DateTimeResponse" Distance: description: A decimal distance (in miles or kilometers) schema: $ref: "#/definitions/DistanceResponse" Forbidden: description: 403 - Forbidden schema: $ref: "#/definitions/ForbiddenResponse" Languages: description: A list of languages supported by the system schema: $ref: "#/definitions/LanguagesResponse" Locales: description: A list of locales schema: $ref: "#/definitions/LocalesResponse" NotFound: description: 404 - Not Found schema: $ref: "#/definitions/NotFoundResponse" PopulatedPlace: description: Populated-place details schema: $ref: "#/definitions/PopulatedPlaceResponse" PopulatedPlaces: description: A list of populated places schema: $ref: "#/definitions/PopulatedPlacesResponse" Region: description: Country region details schema: $ref: "#/definitions/RegionResponse" Regions: description: A list of country regions schema: $ref: "#/definitions/RegionsResponse" Time: description: An ISO-8601 time response schema: $ref: "#/definitions/TimeResponse" TimeZone: description: A time-zone schema: $ref: "#/definitions/TimeZoneResponse" TimeZones: description: A list of time-zones schema: $ref: "#/definitions/TimeZonesResponse" Unauthorized: description: 401 - Unauthorized tags: - description: Geo Endpoints name: Geo - description: Locale Endpoints name: Locale paths: /geo/adminDivisions: get: consumes: - application/json description: | Find administrative divisions, filtering by optional criteria. If no criteria are set, you will get back all known divisions. operationId: findAdminDivisionsUsingGET parameters: - $ref: "#/parameters/query.place.location.id" - $ref: "#/parameters/query.place.location.radiusOf" - $ref: "#/parameters/query.distanceUnit" - $ref: "#/parameters/query.place.countryIds" - $ref: "#/parameters/query.place.excludedCountryIds" - $ref: "#/parameters/query.place.minPopulation" - $ref: "#/parameters/query.place.maxPopulation" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.timeZoneIds" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.place.sort" - $ref: "#/parameters/query.includeDeleted" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlaces" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" summary: Find administrative divisions tags: - Geo "/geo/adminDivisions/{divisionId}": get: consumes: - application/json description: | Get the details for a specific administrative division, including location coordinates, population, and elevation above sea-level (if available). operationId: getAdminDivisionUsingGET parameters: - $ref: "#/parameters/path.divisionId" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.languageCode" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlace" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get administrative division details tags: - Geo "/geo/adminDivisions/{divisionId}/nearbyCities": get: consumes: - application/json description: | Find cities near the given administrative division, filtering by optional criteria. If no criteria are set, you will get back all known cities. operationId: findCitiesNearAdminDivisionUsingGET parameters: - $ref: "#/parameters/path.divisionId" - $ref: "#/parameters/query.place.location.radiusOf" - $ref: "#/parameters/query.distanceUnit" - $ref: "#/parameters/query.place.countryIds" - $ref: "#/parameters/query.place.excludedCountryIds" - $ref: "#/parameters/query.place.minPopulation" - $ref: "#/parameters/query.place.maxPopulation" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.timeZoneIds" - $ref: "#/parameters/query.place.types" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.place.sort" - $ref: "#/parameters/query.includeDeleted" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlaces" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Find cities near division tags: - Geo "/geo/adminDivisions/{divisionId}/nearbyDivisions": get: consumes: - application/json description: | Find administrative divisions near the given origin division, filtering by optional criteria. If no criteria are set, you will get back all known divisions. operationId: findDivisionsNearAdminDivisionUsingGET parameters: - $ref: "#/parameters/path.divisionId" - $ref: "#/parameters/query.place.location.radiusOf" - $ref: "#/parameters/query.distanceUnit" - $ref: "#/parameters/query.place.countryIds" - $ref: "#/parameters/query.place.excludedCountryIds" - $ref: "#/parameters/query.place.minPopulation" - $ref: "#/parameters/query.place.maxPopulation" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.timeZoneIds" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.place.sort" - $ref: "#/parameters/query.includeDeleted" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlaces" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Find divisions near division tags: - Geo /geo/cities: get: consumes: - application/json description: | Find cities, filtering by optional criteria. If no criteria are set, you will get back all known cities. operationId: findCitiesUsingGET parameters: - $ref: "#/parameters/query.place.location.id" - $ref: "#/parameters/query.place.location.radiusOf" - $ref: "#/parameters/query.distanceUnit" - $ref: "#/parameters/query.place.countryIds" - $ref: "#/parameters/query.place.excludedCountryIds" - $ref: "#/parameters/query.place.minPopulation" - $ref: "#/parameters/query.place.maxPopulation" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.timeZoneIds" - $ref: "#/parameters/query.place.types" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.place.sort" - $ref: "#/parameters/query.includeDeleted" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlaces" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" summary: Find cities tags: - Geo "/geo/cities/{cityId}": get: consumes: - application/json description: | Get the details for a specific city, including location coordinates, population, and elevation above sea-level (if available). operationId: getCityUsingGET parameters: - $ref: "#/parameters/path.cityId" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.languageCode" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlace" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get city details tags: - Geo "/geo/cities/{cityId}/dateTime": get: consumes: - application/json description: Get city date-time operationId: getCityDateTimeUsingGET parameters: - $ref: "#/parameters/path.cityId" produces: - application/json responses: "200": $ref: "#/responses/DateTime" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get city date-time tags: - Geo "/geo/cities/{cityId}/distance": get: consumes: - application/json description: Get distance from the given city operationId: getCityDistanceUsingGET parameters: - $ref: "#/parameters/path.cityId" - $ref: "#/parameters/query.toCityId" - $ref: "#/parameters/query.distanceUnit" produces: - application/json responses: "200": $ref: "#/responses/Distance" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get city distance tags: - Geo "/geo/cities/{cityId}/locatedIn": get: consumes: - application/json description: | Get the details for the containing populated place (e.g., its county or other administrative division), including location coordinates, population, and elevation above sea-level (if available). operationId: getCityLocatedInUsingGET parameters: - $ref: "#/parameters/path.cityId" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.languageCode" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlace" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get city admin region tags: - Geo "/geo/cities/{cityId}/nearbyCities": get: consumes: - application/json description: | Find cities near the given origin city, filtering by optional criteria. If no criteria are set, you will get back all known cities. operationId: findCitiesNearCityUsingGET parameters: - $ref: "#/parameters/path.cityId" - $ref: "#/parameters/query.place.location.radiusOf" - $ref: "#/parameters/query.distanceUnit" - $ref: "#/parameters/query.place.countryIds" - $ref: "#/parameters/query.place.excludedCountryIds" - $ref: "#/parameters/query.place.minPopulation" - $ref: "#/parameters/query.place.maxPopulation" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.timeZoneIds" - $ref: "#/parameters/query.place.types" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.place.sort" - $ref: "#/parameters/query.includeDeleted" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlaces" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Find cities near city tags: - Geo "/geo/cities/{cityId}/time": get: consumes: - application/json description: Get city time operationId: getCityTimeUsingGET parameters: - $ref: "#/parameters/path.cityId" produces: - application/json responses: "200": $ref: "#/responses/Time" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get city time tags: - Geo /geo/countries: get: consumes: - application/json description: | Find countries, filtering by optional criteria. If no criteria are set, you will get back all known countries. operationId: getCountriesUsingGET parameters: - $ref: "#/parameters/query.country.currencyCode" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.country.sort" produces: - application/json responses: "200": $ref: "#/responses/Countries" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" summary: Find countries tags: - Geo "/geo/countries/{countryId}": get: consumes: - application/json description: Get the details for a specific country, including number of regions. operationId: getCountryUsingGET parameters: - $ref: "#/parameters/path.countryId" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.languageCode" produces: - application/json responses: "200": $ref: "#/responses/Country" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get country details tags: - Geo "/geo/countries/{countryId}/regions": get: consumes: - application/json description: | Get all regions in a specific country. These could be states, provinces, districts, or otherwise major political divisions. operationId: getRegionsUsingGET parameters: - $ref: "#/parameters/path.countryId" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.region.sort" produces: - application/json responses: "200": $ref: "#/responses/Regions" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Find country regions tags: - Geo "/geo/countries/{countryId}/regions/{regionCode}": get: consumes: - application/json description: Get the details of a specific country region, including number of cities. operationId: getRegionUsingGET parameters: - $ref: "#/parameters/path.countryId" - $ref: "#/parameters/path.regionCode" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.languageCode" produces: - application/json responses: "200": $ref: "#/responses/Region" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get region details tags: - Geo "/geo/countries/{countryId}/regions/{regionCode}/adminDivisions": get: consumes: - application/json description: | Get the administrative divisions in a specific country region. The country and region info is omitted in the response. operationId: findRegionDivisionsUsingGET parameters: - $ref: "#/parameters/path.countryId" - $ref: "#/parameters/path.regionCode" - $ref: "#/parameters/query.place.minPopulation" - $ref: "#/parameters/query.place.maxPopulation" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.timeZoneIds" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.place.sort.withinRegion" - $ref: "#/parameters/query.includeDeleted" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlaces" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Find country region administrative divisions tags: - Geo "/geo/countries/{countryId}/regions/{regionCode}/cities": get: consumes: - application/json description: | Get the cities in a specific country region. The country and region info is omitted in the response. operationId: findRegionCitiesUsingGET parameters: - $ref: "#/parameters/path.countryId" - $ref: "#/parameters/path.regionCode" - $ref: "#/parameters/query.place.minPopulation" - $ref: "#/parameters/query.place.maxPopulation" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.timeZoneIds" - $ref: "#/parameters/query.place.types" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.place.sort.withinRegion" - $ref: "#/parameters/query.includeDeleted" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlaces" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Find country region cities tags: - Geo "/geo/locations/{locationId}/nearbyCities": get: consumes: - application/json description: | Find cities near the given location, filtering by optional criteria. If no criteria are set, you will get back all known cities. operationId: findCitiesNearLocationUsingGET parameters: - $ref: "#/parameters/path.location.id" - $ref: "#/parameters/query.place.location.radiusOf" - $ref: "#/parameters/query.distanceUnit" - $ref: "#/parameters/query.place.countryIds" - $ref: "#/parameters/query.place.excludedCountryIds" - $ref: "#/parameters/query.place.minPopulation" - $ref: "#/parameters/query.place.maxPopulation" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.timeZoneIds" - $ref: "#/parameters/query.place.types" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.place.sort" - $ref: "#/parameters/query.includeDeleted" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlaces" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" summary: Find cities near location tags: - Geo "/geo/locations/{locationId}/nearbyDivisions": get: consumes: - application/json description: | Find administrative divisions near the given location, filtering by optional criteria. If no criteria are set, you will get back all known divisions. operationId: findDivisionsNearLocationUsingGET parameters: - $ref: "#/parameters/path.location.id" - $ref: "#/parameters/query.place.location.radiusOf" - $ref: "#/parameters/query.distanceUnit" - $ref: "#/parameters/query.place.countryIds" - $ref: "#/parameters/query.place.excludedCountryIds" - $ref: "#/parameters/query.place.minPopulation" - $ref: "#/parameters/query.place.maxPopulation" - $ref: "#/parameters/query.entity.namePrefix" - $ref: "#/parameters/query.entity.namePrefixDefaultLangResults" - $ref: "#/parameters/query.timeZoneIds" - $ref: "#/parameters/query.asciiMode" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.languageCode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" - $ref: "#/parameters/query.place.sort" - $ref: "#/parameters/query.includeDeleted" produces: - application/json responses: "200": $ref: "#/responses/PopulatedPlaces" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" summary: Find divisions near location tags: - Geo /locale/currencies: get: consumes: - application/json description: Find currencies, filtering by optional criteria. If no criteria are set, you will get back all known currencies. operationId: getCurrenciesUsingGET parameters: - $ref: "#/parameters/query.currency.countryId" - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" produces: - application/json responses: "200": $ref: "#/responses/Currencies" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" summary: Find currencies tags: - Locale /locale/languages: get: consumes: - application/json description: Get all supported languages operationId: getLanguagesUsingGET parameters: - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" produces: - application/json responses: "200": $ref: "#/responses/Languages" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" summary: Get languages tags: - Locale /locale/locales: get: consumes: - application/json description: Get all known locales operationId: getLocalesUsingGET parameters: - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" produces: - application/json responses: "200": $ref: "#/responses/Locales" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" summary: Get locales tags: - Locale /locale/timezones: get: consumes: - application/json description: Get all known time-zones operationId: getTimezonesUsingGET parameters: - $ref: "#/parameters/query.hateoasMode" - $ref: "#/parameters/query.limit" - $ref: "#/parameters/query.offset" produces: - application/json responses: "200": $ref: "#/responses/TimeZones" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" summary: Get time-zones tags: - Locale "/locale/timezones/{zoneId}": get: consumes: - application/json description: Get time-zone operationId: getTimeZoneUsingGET parameters: - $ref: "#/parameters/path.zoneId" produces: - application/json responses: "200": $ref: "#/responses/TimeZone" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get time-zone tags: - Locale "/locale/timezones/{zoneId}/dateTime": get: consumes: - application/json description: Get time-zone date-time operationId: getTimeZoneDateTimeUsingGET parameters: - $ref: "#/parameters/path.zoneId" produces: - application/json responses: "200": $ref: "#/responses/DateTime" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get time-zone date-time tags: - Locale "/locale/timezones/{zoneId}/time": get: consumes: - application/json description: Get time-zone time operationId: getTimeZoneTimeUsingGET parameters: - $ref: "#/parameters/path.zoneId" produces: - application/json responses: "200": $ref: "#/responses/Time" "400": $ref: "#/responses/BadRequest" "401": $ref: "#/responses/Unauthorized" "403": $ref: "#/responses/Forbidden" "404": $ref: "#/responses/NotFound" summary: Get time-zone time tags: - Locale definitions: BadRequestResponse: allOf: - $ref: "#/definitions/BaseResponse" description: Bad Request Response example: errors: - code: PARAM_INVALID message: "Param [someParam] has invalid value: invalidValue" title: Bad Request Response type: object BaseCollectionResponse: allOf: - $ref: "#/definitions/BaseResponse" - properties: links: items: $ref: "#/definitions/Link" title: Links type: array metadata: $ref: "#/definitions/Metadata" title: Metadata description: Common properties for all collection responses example: links: - href: /data/world/v1/some/resource?offset=0&limit=5 rel: first - href: /data/world/v1/some/resource?offset=0&limit=5 rel: prev - href: /data/world/v1/some/resource?offset=10&limit=5 rel: next - href: /data/world/v1/some/resource?offset=95&limit=5 rel: last metadata: currentOffset: 5 totalCount: 100 title: Base Collection Response type: object BaseResponse: description: Common properties for all responses example: errors: [] properties: errors: items: $ref: "#/definitions/Error" title: Errors type: array title: Base Response type: object CountriesResponse: allOf: - $ref: "#/definitions/BaseCollectionResponse" - properties: data: items: $ref: "#/definitions/CountrySummary" title: CountrySummaries type: array description: A list of countries example: data: - code: SM currencyCodes: - EUR name: San Marino wikiDataId: Q238 - code: NE currencyCodes: - XOF name: Niger wikiDataId: Q1032 - code: MT currencyCodes: - EUR name: Malta wikiDataId: Q233 - code: KZ currencyCodes: - KZT name: Kazakhstan wikiDataId: Q232 - code: KE currencyCodes: - KES name: Kenya wikiDataId: Q114 links: - href: /data/world/v1/geo/countries?offset=0&limit=5 rel: first - href: /data/world/v1/geo/countries?offset=0&limit=5 rel: prev - href: /data/world/v1/geo/countries?offset=10&limit=5 rel: next - href: /data/world/v1/geo/countries?offset=195&limit=5 rel: last metadata: currentOffset: 5 totalCount: 198 title: Countries Response type: object CountryDetails: description: Full country details example: callingCode: "+1" code: US currencyCodes: - USD flagImageUri: http://commons.wikimedia.org/wiki/Special:FilePath/Flag%20of%20the%20United%20States.svg name: United States numRegions: 56 wikiDataId: Q30 properties: callingCode: description: The country dialing prefix type: string code: description: The ISO-3166 country code type: string currencyCodes: description: A list of supported ISO-4217 currency codes items: type: string type: array flagImageUri: description: The country flag image type: string name: description: The country name (varies by languageCode) type: string numRegions: description: The number of regions in this country format: int32 type: integer wikiDataId: description: The country WikiData id type: string title: Country Details type: object CountryResponse: allOf: - $ref: "#/definitions/BaseResponse" - properties: data: $ref: "#/definitions/CountryDetails" description: Country details response example: data: callingCode: "+1" code: US currencyCodes: - USD flagImageUri: http://commons.wikimedia.org/wiki/Special:FilePath/Flag%20of%20the%20United%20States.svg name: United States numRegions: 56 wikiDataId: Q30 title: Country Response type: object CountrySummary: description: Minimal country info example: code: US currencyCodes: - USD name: United States wikiDataId: Q30 properties: code: description: The ISO-3166 country code type: string currencyCodes: description: A list of supported ISO-4217 currency codes items: type: string type: array name: description: The country name (varies by languageCode) type: string wikiDataId: description: The country WikiData id type: string title: Country Summary type: object CurrenciesResponse: allOf: - $ref: "#/definitions/BaseCollectionResponse" - properties: data: items: $ref: "#/definitions/Currency" type: array description: A list of currencies example: data: - code: AWG countryCodes: - AW - code: AZN countryCodes: - AZ - code: BAM countryCodes: - BA - code: BBD countryCodes: - BB - code: BDT countryCodes: - BD links: - href: /data/world/v1/locale/currencies?offset=0&limit=5 rel: first - href: /data/world/v1/locale/currencies?offset=5&limit=5 rel: prev - href: /data/world/v1/locale/currencies?offset=15&limit=5 rel: next - href: /data/world/v1/locale/currencies?offset=200&limit=5 rel: last metadata: currentOffset: 10 totalCount: 205 title: Currencies Response type: object Currency: description: Currency info example: code: USD countryCodes: - PR - MP - IO - FM - PW - GU - BQ - TC - VG - AS - VI - TL - UM - MH - EC - US symbol: $ properties: code: description: The ISO-4217 currency code type: string countryCodes: description: A list of ISO-3166 country codes of countries supporting this currency items: type: string type: array symbol: description: The currency symbol type: string title: Currency type: object DateTimeResponse: allOf: - $ref: "#/definitions/BaseResponse" - properties: data: description: "The date-time in ISO-6801 format: yyyyMMdd'T'HHmmssZ" format: date-time type: string description: An ISO-6801 date-time response example: data: 2020-10-05T01:16:53.504604+04:30 title: Date-Time Response type: object DistanceResponse: allOf: - $ref: "#/definitions/BaseResponse" - properties: data: description: The distance in units as set by the distanceUnit param (defaults to miles) format: double type: number description: A decimal distance (in miles or kilometers) example: data: 6707.9 title: Distance Response type: object Error: description: An error that occurred processing the request example: code: ENTITY_NOT_FOUND message: "Param [someParam] has invalid value: invalidValue" properties: code: $ref: "#/definitions/ErrorCode" message: type: string title: Error type: object ErrorCode: description: | One of a set of enumerated error codes representing the types of errors that can occur processing a request enum: - ACCESS_DENIED - ENTITY_NOT_FOUND - INCOMPATIBLE - PARAM_INVALID - PARAMS_MUTUALLY_EXCLUSIVE - REQUEST_UNPROCESSABLE example: ENTITY_NOT_FOUND title: ErrorCode type: string ForbiddenResponse: allOf: - $ref: "#/definitions/BaseResponse" description: Forbidden Response example: errors: - code: ACCESS_DENIED message: The reason why access was denied title: Forbidden Response type: object LanguageDescriptor: description: A language supported by the service example: code: en name: English properties: code: enum: - undefined - aa - ab - ae - af - ak - am - an - ar - as - av - ay - az - ba - be - bg - bh - bi - bm - bn - bo - br - bs - ca - ce - ch - co - cr - cs - cu - cv - cy - da - de - dv - dz - ee - el - en - eo - es - et - eu - fa - ff - fi - fj - fo - fr - fy - ga - gd - gl - gn - gu - gv - ha - he - hi - ho - hr - ht - hu - hy - hz - ia - id - ie - ig - ii - ik - io - is - it - iu - ja - jv - ka - kg - ki - kj - kk - kl - km - kn - ko - kr - ks - ku - kv - kw - ky - la - lb - lg - li - ln - lo - lt - lu - lv - mg - mh - mi - mk - ml - mn - mr - ms - mt - my - na - nb - nd - ne - ng - nl - nn - no - nr - nv - ny - oc - oj - om - or - os - pa - pi - pl - ps - pt - qu - rm - rn - ro - ru - rw - sa - sc - sd - se - sg - si - sk - sl - sm - sn - so - sq - sr - ss - st - su - sv - sw - ta - te - tg - th - ti - tk - tl - tn - to - tr - ts - tt - tw - ty - ug - uk - ur - uz - ve - vi - vo - wa - wo - xh - yi - yo - za - zh - zu type: string name: type: string title: Language type: object LanguagesResponse: allOf: - $ref: "#/definitions/BaseCollectionResponse" - properties: data: items: $ref: "#/definitions/LanguageDescriptor" type: array description: A list of languages supported by the system example: data: - code: fr name: French - code: it name: Italian - code: pt name: Portuguese links: - href: /data/world/v1/locale/languages?offset=0&limit=3 rel: first - href: /data/world/v1/locale/languages?offset=0&limit=3 rel: prev - href: /data/world/v1/locale/languages?offset=6&limit=3 rel: next - href: /data/world/v1/locale/languages?offset=6&limit=3 rel: last metadata: currentOffset: 3 totalCount: 8 title: Languages Response type: object Link: description: A HATEAOS link example: href: /data/world/v1/geo/cities?offset=10&limit=10 rel: next properties: href: type: string rel: type: string title: Link type: object Locale: description: A locale representing a language/region combination example: code: en_US properties: code: description: The locale code type: string title: Locale type: object LocalesResponse: allOf: - $ref: "#/definitions/BaseCollectionResponse" - properties: data: items: $ref: "#/definitions/Locale" type: array description: A list of locales example: data: - code: eu - code: ar_MR - code: es_DO - code: ru - code: az links: - href: /data/world/v1/locale/locales?offset=0&limit=5 rel: first - href: /data/world/v1/locale/locales?offset=45&limit=5 rel: prev - href: /data/world/v1/locale/locales?offset=55&limit=5 rel: next - href: /data/world/v1/locale/locales?offset=770&limit=5 rel: last metadata: currentOffset: 50 totalCount: 772 title: Locales Response type: object Metadata: description: Result metadata (currently only associated with collection results) example: currentOffset: 0 totalCount: 100 properties: currentOffset: description: The zero-ary offset into the results (0 is the first result) format: int64 type: integer totalCount: description: The total number of results across pages format: int64 type: integer title: Metadata type: object NotFoundResponse: allOf: - $ref: "#/definitions/BaseResponse" description: Not Found Response example: errors: - code: ENTITY_NOT_FOUND message: "Entity not found for id: someEntityId" title: Not Found Response type: object PopulatedPlaceDetails: description: Full populated-place details example: country: United States of America countryCode: US deleted: false elevationMeters: 10 id: 123214 latitude: 40.67 longitude: -73.94 name: New York City population: 8398748 region: New York regionCode: NY timezone: America__New_York type: CITY wikiDataId: Q60 properties: country: description: The country name (varies by languageCode) type: string countryCode: description: The ISO-3166 country code type: string deleted: description: If this place has been soft-deleted type: boolean elevationMeters: description: The place elevation (meters) above sea level format: int32 type: integer id: description: The place GeoDB native id format: int32 type: integer latitude: description: The place latittude (-90.0 to 90.0) format: double type: number longitude: description: The place longitude (-180.0 to 180.0) format: double type: number name: description: The place name (varies by languageCode) type: string population: description: The place population format: int32 type: integer region: description: The region name (varies by languageCode) type: string regionCode: description: The ISO or FIPS region code type: string timezone: description: The place timezone id type: string type: $ref: "#/definitions/PopulatedPlaceType" description: The place type wikiDataId: description: The place WikiData id type: string title: Populated-Place Details type: object PopulatedPlaceResponse: allOf: - $ref: "#/definitions/BaseResponse" - properties: data: $ref: "#/definitions/PopulatedPlaceDetails" description: Populated-place details response example: data: country: United States of America countryCode: US deleted: false elevationMeters: 10 id: 123214 latitude: 40.67 longitude: -73.94 name: New York City population: 8398748 region: New York regionCode: NY timezone: America__New_York type: CITY wikiDataId: Q60 title: Populated-Place Response type: object PopulatedPlaceSummary: description: Minimal populated-place info example: country: United States of America countryCode: US id: 123214 latitude: 40.67 longitude: -73.94 name: New York City region: New York regionCode: NY type: CITY wikiDataId: Q60 properties: country: description: The country name (varies by languageCode) type: string countryCode: description: The ISO-3166 country code type: string distance: description: Included if this is the result of a distance query format: double type: number id: description: The place GeoDB native id format: int32 type: integer latitude: description: The place latittude (-90.0 to 90.0) format: double type: number longitude: description: The place longitude (-180.0 to 180.0) format: double type: number name: description: The place name (varies by languageCode) type: string population: description: The place population format: int32 type: integer region: description: The region name (varies by languageCode) type: string regionCode: description: The ISO or FIPS region code type: string type: $ref: "#/definitions/PopulatedPlaceType" description: The place type wikiDataId: description: The place WikiData id type: string type: object PopulatedPlaceType: description: | One of a set of enumerated populated-place types known by the service (currently only level-2 admin divisions and cities) enum: - ADM2 - CITY example: CITY type: string PopulatedPlacesResponse: allOf: - $ref: "#/definitions/BaseCollectionResponse" - properties: data: items: $ref: "#/definitions/PopulatedPlaceSummary" type: array description: A list of populated places example: data: - country: Andorra countryCode: AD id: 2987553 latitude: 42.57777778 longitude: 1.61944444 name: L'Aldosa de Canillo region: Canillo regionCode: 2 type: CITY wikiDataId: Q24371 - country: Andorra countryCode: AD id: 3086756 latitude: 42.57667 longitude: 1.51773 name: La Cortinada region: Ordino regionCode: 5 type: CITY wikiDataId: Q24486 - country: Andorra countryCode: AD id: 3056764 latitude: 42.4859 longitude: 1.49045 name: La Margineda region: Andorra la Vella regionCode: 7 type: CITY wikiDataId: Q2536296 - country: Andorra countryCode: AD id: 978 latitude: 42.544354 longitude: 1.515427 name: La Massana region: La Massana regionCode: 4 type: CITY wikiDataId: Q3820973 - country: Andorra countryCode: AD id: 759 latitude: 42.5 longitude: 1.53333333 name: Les Escaldes region: Escaldes-Engordany regionCode: "08" type: CITY wikiDataId: Q1050185 links: - href: /data/world/v1/geo/cities?offset=0&limit=5 rel: first - href: /data/world/v1/geo/cities?offset=0&limit=5 rel: prev - href: /data/world/v1/geo/cities?offset=10&limit=5 rel: next - href: /data/world/v1/geo/cities?offset=273685&limit=5 rel: last metadata: currentOffset: 5 totalCount: 273690 title: Populated-Places Response type: object RegionDetails: description: Full country region details example: capital: Sacramento countryCode: US fipsCode: 6 isoCode: CA name: California numCities: 1532 wikiDataId: Q99 properties: capital: description: The region's capital city (varies by languageCode) type: string countryCode: description: An ISO-3166 country code type: string fipsCode: description: The FIPS 10-4 region code type: string isoCode: description: The ISO region code type: string name: description: The region name (varies by languageCode) type: string numCities: description: The number of cities in this region format: int32 type: integer wikiDataId: description: The region WikiData id type: string title: Country Region Details type: object RegionResponse: allOf: - $ref: "#/definitions/BaseResponse" - properties: data: $ref: "#/definitions/RegionDetails" description: Country region details response example: data: capital: Sacramento countryCode: US fipsCode: 6 isoCode: CA name: California numCities: 1532 wikiDataId: Q99 title: Country Region Response type: object RegionSummary: description: Minimal country region info example: countryCode: US fipsCode: 6 isoCode: CA name: California wikiDataId: Q99 properties: countryCode: description: An ISO-3166 country code type: string fipsCode: description: The FIPS 10-4 region code type: string isoCode: description: The ISO region code type: string name: description: The region name (varies by languageCode) type: string wikiDataId: description: The region WikiData id type: string title: Country Region Summary type: object RegionsResponse: allOf: - $ref: "#/definitions/BaseCollectionResponse" - properties: data: description: A list of RegionSummaries items: $ref: "#/definitions/RegionSummary" type: array description: A list of country regions example: data: - countryCode: US fipsCode: 48 isoCode: TX name: Texas wikiDataId: Q1439 - countryCode: US fipsCode: 39 isoCode: OH name: Ohio wikiDataId: Q1397 - countryCode: US fipsCode: 31 isoCode: NE name: Nebraska wikiDataId: Q1553 - countryCode: US fipsCode: 50 isoCode: VT name: Vermont wikiDataId: Q16551 - countryCode: US fipsCode: 15 isoCode: HI name: Hawaii wikiDataId: Q782 links: - href: /data/world/v1/geo/countries/US/regions?offset=0&limit=5 rel: first - href: /data/world/v1/geo/countries/US/regions?offset=0&limit=5 rel: prev - href: /data/world/v1/geo/countries/US/regions?offset=10&limit=5 rel: next - href: /data/world/v1/geo/countries/US/regions?offset=55&limit=5 rel: last metadata: currentOffset: 5 totalCount: 56 title: Country Regions Response type: object TimeResponse: allOf: - $ref: "#/definitions/BaseResponse" - properties: data: description: "The time in ISO-8601 format: HHmmss.SSSZ" type: string description: An ISO-8601 time response example: data: 19:21:38.796217 title: Time Response type: object TimeZoneDescriptor: description: A time-zone example: id: Africa__Abidjan name: Greenwich Mean Time rawUtcOffsetHours: 0 properties: id: description: The time-zone id type: string name: description: The time-zone name type: string rawUtcOffsetHours: description: The number of hours this time-zone is offset from UTC format: int32 type: integer title: Time-Zone type: object TimeZoneResponse: allOf: - $ref: "#/definitions/BaseResponse" - properties: id: description: The time-zone id type: string name: description: The time-zone name type: string rawUtcOffsetHours: description: The number of hours this time-zone is offset from UTC format: int32 type: integer description: A time-zone example: data: id: America__Marigot name: Atlantic Standard Time rawUtcOffsetHours: -4 title: Time-Zone Response type: object TimeZonesResponse: allOf: - $ref: "#/definitions/BaseCollectionResponse" - properties: data: items: $ref: "#/definitions/TimeZoneDescriptor" type: array description: A list of time-zones example: data: - id: America__Marigot name: Atlantic Standard Time rawUtcOffsetHours: -4 - id: Asia__Aqtau name: West Kazakhstan Time rawUtcOffsetHours: 5 - id: Pacific__Kwajalein name: Marshall Islands Time rawUtcOffsetHours: 12 - id: America__El_Salvador name: Central Standard Time rawUtcOffsetHours: -6 - id: Asia__Pontianak name: Western Indonesia Time rawUtcOffsetHours: 7 links: - href: /data/world/v1/locale/timezones?offset=0&limit=5 rel: first - href: /data/world/v1/locale/timezones?offset=0&limit=5 rel: prev - href: /data/world/v1/locale/timezones?offset=10&limit=5 rel: next - href: /data/world/v1/locale/timezones?offset=595&limit=5 rel: last metadata: currentOffset: 5 totalCount: 600 title: Time-Zones Response type: object