> ## Documentation Index
> Fetch the complete documentation index at: https://www.mapsdata.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up locations

> Find a city label that maps exactly to the Mapsdata search UI.

Search the bundled city catalog. The endpoint returns up to eight prefix matches and consumes no lead credits.

<ParamField query="q" type="string" required>
  City name, between 2 and 100 characters. Example: `New York`.
</ParamField>

<ParamField query="country" type="string">
  Optional two-letter country code used to disambiguate matches. Example: `US`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://www.mapsdata.io/api/v1/locations?q=New%20York&country=US" \
    -H "x-api-key: md_live_your_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "locations": [
      {
        "location_code": 1023191,
        "name": "New York",
        "full_name": "New York, New York, United States",
        "country_code": "US",
        "location_name": "New York,New York,United States",
        "city": "New York",
        "region": "New York",
        "country": "US",
        "location_type": "City",
        "label": "New York, New York"
      }
    ]
  }
  ```
</ResponseExample>

## Map the response to a search

The dashboard selects `label`, not `location_code`. To reproduce the UI request exactly:

```json theme={null}
{
  "input": {
    "query": "plumber",
    "location": "New York, New York",
    "countryCode": "US",
    "maxResults": 100,
    "language": "en"
  }
}
```

<ResponseField name="locations[].label" type="string">Send this value as `input.location`.</ResponseField>
<ResponseField name="locations[].country_code" type="string">Send this value as `input.countryCode`.</ResponseField>
<ResponseField name="locations[].location_code" type="integer">Stable catalog identifier returned for interoperability. The current search endpoint does not accept it.</ResponseField>
<ResponseField name="locations[].full_name" type="string">Fully qualified city, region, and country name for display or storage.</ResponseField>

<div className="callout mint-my-5 mint-rounded-xl mint-border mint-border-[#656c2e]/30 mint-bg-[#656c2e]/10 mint-px-5 mint-py-4 mint-text-sm mint-text-[#4d5321]">
  Do not send only <code>New York</code> when a catalog match is available. Using <code>New York, New York</code> plus <code>countryCode: US</code> avoids ambiguous markets and matches the UI.
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.