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

GET /v1/places/autocomplete - Search as the user types
GET /v1/places/validate - Validate a full address
GET /v1/places/postal-format - Postcode format per country

Place Details