API Documentation - Endpoints & Examples

Place Details

Everything you need once the user picks a suggestion

The /v1/places/details endpoint takes the id of an autocomplete suggestion and returns the complete record: the full hierarchy, the postcode format of the country and the data a form usually needs next — phone prefix, currency, timezones.

Endpoint

GET https://api.countrydataapi.com/v1/places/details

Query Parameters

Parameter Type Required Description
apikey string Yes Your API authentication key
id string Yes The id returned by /v1/places/autocomplete
type string Yes country, state or city — the type of the suggestion
lang string No Language of the returned names. Defaults to en
sessiontoken string No The session token used during autocomplete. Makes this call free

Request Example

curl "https://api.countrydataapi.com/v1/places/details?apikey=your-api-key&id=66c7a6c9e4bda21f4ab1a0f1&type=city"

JavaScript

async function getDetails(suggestion, sessionToken) {
  const params = new URLSearchParams({
    apikey: 'your-api-key',
    id: suggestion.id,
    type: suggestion.type,
    sessiontoken: sessionToken,
  });

  const response = await fetch(
    `https://api.countrydataapi.com/v1/places/details?${params}`
  );
  const { place } = await response.json();
  return place;
}

TypeScript SDK

const { place } = await api.places.details({
  id: suggestion.id,
  type: suggestion.type,
  sessiontoken: session,
});

place.components.country?.phone_code; // "+34"
place.postal.regex;                   // "^\\d{5}$"

Response Format

{
  "success": true,
  "place": {
    "id": "66c7a6c9e4bda21f4ab1a0f1",
    "type": "city",
    "name": "Madrid",
    "description": "Madrid, Comunidad de Madrid, Spain",
    "components": {
      "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madrid" },
      "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Comunidad de Madrid" },
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "Spain",
        "iso2": "ES",
        "iso3": "ESP",
        "phone_code": "+34",
        "flag": "🇪🇸"
      }
    },
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345"
    },
    "location": null,
    "country_info": {
      "currencies": [{ "code": "EUR", "name": "Euro", "symbol": "€" }],
      "languages": ["Spanish"],
      "timezones": ["UTC+01:00"],
      "continent": "EU",
      "region": "Europe"
    }
  },
  "tokens_used": 0,
  "remaining_tokens": 4871
}

Response Fields

Field Type Description
place.components object Full hierarchy: city, state, country
place.postal.format string Template: # is a digit, @ is a letter
place.postal.regex string Official postcode pattern for the country
place.postal.example string Sample value derived from format and checked against regex
place.location object Coordinates — see the note below
place.country_info object Currencies, languages, timezones, continent and region

About location

location is only populated for type=country, where it carries the country centroid and "precision": "country".

For states and cities it is null. The dataset is administrative and has no per-city coordinates, and returning the country centroid labelled as a city would be worse than returning nothing. If you need city-level coordinates or geocoding, this endpoint is not the right tool.

Token Usage

  • 0 tokens when sessiontoken matches an open autocomplete session. The session was already charged on the first keystroke, and this call closes it.
  • 1 token otherwise.

This means a complete address field — however many keystrokes plus the final details lookup — costs a single token.

Error Response

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No city found with id \"abc\".",
    "status": 404
  },
  "message": "No city found with id \"abc\"."
}

Related Endpoints