Official ParseAPI client for Python.
pip install parseapifrom parseapi import ParseAPI
parse = ParseAPI("your-api-key")
country = parse.country("US")Get a key at parseapi.com. The client also reads PARSEAPI_KEY from the environment.
State and County use iso_code for the full ISO 3166-2 code of the exact returned place, including County items in State lists. A null means unassigned or unknown. National state and county identifiers are unchanged. Update State readers from iso_subdivision to iso_code. Responses keep the server's keys without adding legacy duplicates.
This SDK explicitly selects the API contract supported by this SDK. It sends X-API-Version: 2.2.0 on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same. The API still accepts earlier Parse-Version request pins.
Upgrade the dependency in staging, review the release notes, and test the application before deploying the same code and dependency version to production. Commit your dependency lockfile so the tested package travels with your deployment. Future major SDK upgrades can select a newer API contract.
Older SDKs keep their existing version selection. Requests without either version header use that default, managed in Dashboard API version. Keep it unchanged while older applications depend on it. Rolling back to an SDK without a version header restores the team default, so rollback only restores the old contract when that default has stayed unchanged.
The package owns its supported API version. For direct HTTP integrations, an explicit X-API-Version header selects a supported contract. See API versions and migration.
Start with the postal code, then pass its coordinates to weather. Reuse the client from the example above.
place = parse.postal("28202", country="US")
lat, lon = place["latitude"], place["longitude"]
if lat is not None and lon is not None:
weather = parse.weather(lat, lon)
print(weather)The coordinates represent the postal area. Weather is for that point. Missing coordinates skip the weather lookup. This composition performs two ordinary lookups when coordinates are available, with the retry policy below.
Pass country when a postal code or national phone number needs disambiguation. A complete international phone number already carries its country context. For a numeric date such as 03/04/2026, supply the intended format. Defaults resolve what the input establishes. Ambiguous input needs your context.
Results are plain data. Pass a returned code or coordinate to another operation when the task needs it. Check nullable values before composing the next call.
Use parse.postal("28202", country="US", deep=True) for US ZIP tax references. tax.name names the levy and tax.rate is a percentage, so 7.9 means 7.9%. The state, county, city and special components explain that combined rate. An exact address can differ. Country and state lookups provide their own geographic reference rates, which should not be added to the ZIP rate. None means unknown and 0 means known zero.
Find candidates, then fetch the profile you selected.
candidates = parse.company.search(query="GitLab", country="US", limit=5)
selected_id = "co_caczn6wf36hj" # Explicitly chosen after reviewing candidates.
profile = parse.company.id(selected_id, deep=True)
if candidates["next"] is not None:
next_page = parse.company.search(
query="GitLab", country="US", limit=5, cursor=candidates["next"]
)Use at most one selector: query for a name, domain, ticker, or identifier; country or exact industry filters also allow discovery without a selector. The API validates selectors and filters. Use country to scope candidates, exchange with a ticker, and authority with an identifier. Search returns companies and an opaque next cursor. Review candidate identity and match details before choosing a stable Company ID. Pass next as cursor with the same selector, filters and limit to continue that result set.
Directory profiles are plain JSON data. Optional detail belongs to each company in search results and adds legal/reference detail plus nullable description, logo, founded, and the social_profiles, phone_numbers, email_addresses, domains and sources collections. A logo is a reported URL. founded has value and precision, distinct from incorporation. Sources identify the website, filing or business register, supported fields and observation/update timestamps. Employee observations retain count, measurement date, organization scope and approximation; null means unknown. Missing, null, empty and unknown fields retain their response values. An empty search is a successful result. Invalid inputs and unknown IDs raise the existing API error.
The public-directory service retires national-number Company lookups in both API versions. Use the directory methods with API 2.1.0.
Company directory social profiles include platform and url. Known handles are included when available; unknown handles may be omitted or returned as null by older servers. Phone and email records use type for the source-reported purpose. Earlier response fields remain readable by the client.
The recipe requests one candidate page, one explicitly chosen profile, plus a second page when a cursor is returned. Each operation uses the existing retry settings. The number-validation call remains unchanged. lang applies to national company-number lookup, while directory calls use the source labels.
AsyncParseAPI exposes the same company, company.id and company.search calls with await.
Discovery example: parse.company.search(country="US", industry="0700", industry_type="sic")
Supply industry and industry_type together. The supported namespace is sic, with an exact four-digit string such as 0700; leading zeros are meaningful. Country-only discovery is also supported. Filters intersect and may narrow an existing selector. Country matches the profile country, not a headquarters or operating-presence claim. Unknown values do not match a requested filter. Filter-only candidates use match.field: "filters" and match.value: null; reuse the same filters and limit with a returned cursor.
Country uses iso_alpha3 and iso_numeric, State uses the full
iso_code code such as US-CA, Language uses iso_alpha3, and Currency
uses iso_numeric. Primary country, state, language and currency codes
keep their meaning. Results retain the selected API contract's exact keys,
values, nulls and nesting. Earlier server contracts retain their earlier ISO
spellings. Use the existing lookup methods for each resource.
One method per endpoint, named after the route.
parse.ip("8.8.8.8")
parse.ip.self()
parse.email("hello@gmail.com")
parse.card("424242")
parse.phone("+14155552671")
parse.carrier("+14155552671")
parse.caller("+14155552671")
parse.hlr("+14155552671")
parse.postal("SW1A 1AA")
parse.postal("28202", country="US")
parse.postal.nearby("28202", country="US", radius=40)
parse.postal.distance("28202", "10001", country="US")
parse.address("1600 Pennsylvania Ave NW, Washington DC", country="US")
parse.address.search("1600 Pennsylvania", country="US", postal="20500")
parse.company("51 824 753 556", country="AU")
parse.company.id("co_caczn6wf36hj", deep=True)
parse.company.search(domain="about.gitlab.com")
parse.company.search(ticker="GTLB", exchange="Nasdaq")
parse.company.search(identifier="0001653482", authority="sec")
parse.city("charlotte", country="US")
parse.city.id("city_mb8mbqrkz8zb")
parse.city.search("char", country="US", limit=10)
parse.city.nearest(35.2271, -80.8431)
parse.city.nearby("denver", radius=8, unit="mi")
parse.country("US")
parse.country.states("US")
parse.state("colorado")
parse.state("NC", country="US")
parse.state.counties("NC", country="US")
parse.county("37081")
parse.continent("NA")
parse.continent.countries("NA")
parse.currency("USD")
parse.currency.rate("USD", "EUR")
parse.language("en")
parse.name("BILLY OSHALL")
parse.name("Andrea", country="IT", deep=True)
parse.name("Robert James Smith", deep=True, name_locale="en")
parse.time() # UTC now
parse.time("America/New_York")
parse.time("America/New_York", at="2026-09-05T15:00:00", to="Europe/London")
parse.time.at(39.77, -104.9)
parse.date("03/04/2026", format="mdy")
parse.date.today()
parse.holiday("US", year=2026)
parse.holiday.date("US", "2026-12-25")
parse.elevation(35.2271, -80.8431)
parse.point(36.0726, -79.792)
parse.weather(40.7128, -74.006)
parse.domain("example.com")
parse.asn("AS13335")
parse.mx("example.com")
parse.dns("example.com")
parse.dns("_dmarc.example.com", type="TXT")
parse.useragent(ua_string)
parse.industry("541511")
parse.industry.search("coffee shop", limit=5)
parse.emoji("rocket")
parse.emoji.search("fire")The existing NAICS lookup and search methods remain available as compatibility names for Industry.
Industry paid deep records include classification exclusions, each with a description and linked codes. Generic exclusions can have no linked codes. Omitted or null exclusions in older responses remain unknown. Search results also include match: the matched field (name, term or naics) and text, plus corrections with from and to tokens for typo fallback. Corrections are empty for exact, plural and prefix matches. Direct code lookups omit match. Older responses may omit it.
Responses are plain dicts, exactly the JSON the API returns. country.states("US") requests states directly; it does not fetch a country first. Required inputs are positional and optional behavior uses keyword arguments, leaving room for new options without changing existing calls. Reuse a client across calls. Use with ParseAPI(...) as parse: or call parse.close() when finished.
DNS uses pooled requests on every plan. Omit type to check A, AAAA, CNAME, MX, NS, TXT, SOA, CAA, SRV and PTR. Records contain name, type, ttl in seconds and a DNS presentation value. TXT values retain quoting and chunk boundaries. A selected question can include its CNAME chain. Empty records mean no records. Lookup failures remain errors.
Same lookup methods and keyword arguments, with await. Use a context manager to close the client when the work is done.
from parseapi import AsyncParseAPI
async with AsyncParseAPI("your-api-key") as parse:
country = await parse.country("US")Name paid deep includes flat short, directory, and initials fields beside gender. name_locale selects CLDR formatting rules and defaults to en. It changes formatting only. Country remains gender context, and unavailable formatting is null. Older responses may omit these fields.
Choose display names for one request:
parse.country("DE", lang="fr")lang is optional on geography lookups and their lists/searches, Currency lookup, Language, Date, Time/Timezone, Emoji lookup/search. IP, ASN and national Company number lookups also accept it for their geographic labels. Codes, native names, quantities and response structure retain their meanings. Source coverage determines which labels are translated; unavailable labels use the API's documented fallback.
The next call keeps its usual default unless it also supplies lang. Existing deep rules still apply. Date format remains an explicit input-parsing control.
time returns local ISO at with its UTC offset and integer Unix seconds in unix. The core offset preserves exact precision. Optional offset_seconds gives the numeric offset, while offset_minutes gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted at means now. With to or targets, an offsetless at is source wall time. Otherwise it is UTC. Include an offset for repeated local times around a clock change. Current time and conversion use pooled requests on every plan. Coordinate clock fields can be null when the timezone is unknown. Existing timezone methods remain supported.
For an offsetless at with to or targets, choose how to handle a clock change with disambiguation. It applies to named-zone and coordinate Time calls.
| Value | Repeated time | Skipped time |
|---|---|---|
compatible (default) |
Earlier occurrence | Shift forward by the clock change |
earlier |
Earlier occurrence | Shift backward by the clock change |
later |
Later occurrence | Shift forward by the clock change |
reject |
400 ambiguous_time |
400 nonexistent_time |
An explicit UTC offset selects an instant directly. For example, 2026-11-01T01:30:00-04:00 and 2026-11-01T01:30:00-05:00 identify the two New York occurrences. A valid disambiguation value has no effect on explicit instants, current-time requests or lookups without to or targets. For user-entered appointment times, start with reject. Handle ambiguous_time or nonexistent_time by collecting an explicit offset or an earlier/later choice from the user. Other malformed input still uses invalid_request.
result = parse.time("America/New_York", at="2026-11-01T01:30:00",
to="UTC", disambiguation="later")
print(result["to"]["at"]) # 2026-11-01T06:30:00+00:00Canonical Time deep includes the pinned rule edition in timezone_database_version and source-wall resolution in resolution. Resolution records kind (unique, overlap or gap), the selected policy, signed adjustment_seconds, and chronological alternatives with exact at, Unix seconds and UTC offset. Unique times have an empty alternatives list. Explicit instants, current time and lookups without conversion omit resolution. Destination detail stays compact.
Search serving IANA IDs by city or region, or omit the query to list all (Go and Rust use an empty string). Discovery returns timezone_database_version and sorted timezones. No search matches returns timezones: [].
Pass targets to convert one instant to 1-10 zones in a single pooled request. The native list preserves order and duplicates. Use targets instead of to. The response adds targets, with optional detail inside each target. Unknown source coordinates return targets: null. An unknown destination rejects the whole request with not_found. Omission keeps the original response shape.
zones = parse.time.zones('New York')
result = parse.time('UTC', at='2026-09-24T12:00:00Z',
targets=['America/New_York', 'Asia/Tokyo'])
print(zones['timezones'], result['targets'])parse.time(iata="JFK", deep=True) and parse.time.zones(country="US", dst=False, observes_dst=True, details=True).
Choose one explicit location input: IP, exact city name or stable city ID, country, IATA airport, ICAO airport, port UN/LOCODE, or address. Country and state can narrow a city or address. State requires country. Address lookup requires US country context and a strict address-point match. Port lookup covers the reviewed port subset, not every assigned UN/LOCODE. IP lookup always uses the supplied IP.
Location calls add location with status, candidates, truncated, source and the typed input. Check status before using the clock: ambiguous or missing locations retain null time fields. Candidate coordinates and IDs can also be null. A country with multiple timezones does not silently choose one. Named-zone and coordinate calls retain their existing signatures.
Timezone discovery accepts country, IANA area, exact signed offset, abbreviation, DST-at-instant and observes-DST-during-year filters. at selects the common instant, sort selects timezone or offset order, and details adds zones rows plus the evaluation at. The default timezones list stays compact. False DST filters are sent explicitly. An abbreviation returns candidate zones rather than choosing one. Observes-DST uses the UTC calendar year containing at.
Source deep adds standard_offset, standard_offset_seconds, signed dst_offset_seconds and season. Seasonal adjustments can be negative. season describes the current DST-flag interval, or the next within 400 days, with actual before/after transition facts and signed change_seconds. Unknown boundaries remain null. These fields are optional and nullable, and destination deep stays compact.
Country Core contains the everyday reference: name, name_full, name_local, demonym, iso_alpha3 and iso_numeric country identifiers, continent, region and subregion, currency, calling code, flag, language and timezone codes, borders, bloc memberships and capital: { name, latitude, longitude }. Paid Deep adds specialist detail, including population, total area and national statistics. gdp_usd and gdp_per_capita_usd are current US dollars; population_growth_percent, urban_population_percent and internet_users_percent use a 0–100 percent scale (growth can be negative or exceed 100). GDP per person and these three percentages round once to two decimals in the API response. elevation_average is average terrain elevation in meters; lowest_point.elevation and highest_point.elevation keep their point-specific meaning. Unknown stays null and a known zero stays zero. Country tax references are grouped once as tax: { name, rate }; the rate remains a percentage. Read capital from the Core object and read optional tax references from tax.name and tax.rate on that same resource.
Country includes postal_format and postal_regex on every plan without requesting Deep. postal_format is an input hint based on one example, not a complete mask. postal_regex checks syntax, not whether a code exists or receives mail. Unavailable values are null.
Australian postal lookups include core localities with suburb choices (city, state, state_name) on every plan. Null or an omitted field means unknown, while [] means the reviewed reference has no eligible choices. city stays null when the source is ambiguous, even if there is only one eligible choice. Let the user select their suburb and keep manual entry available. These are geographic choices, not mailing-address verification. G-NAF source, adaptations and licence.
Postal paid Deep includes currency, neighbors, grouped tax and property_tax: { annual_median }. Property-tax amounts use currency. Tax contains name, rate and the rate_state, rate_county, rate_city and rate_special components in percent. Core provides the postal location answer.
District paid profiles include property_tax where supported. It contains annual_median, currency and period: median annual property tax payable on owner-occupied homes in the statistical area. The amount is adjusted to the final year of the reporting period (YYYY-YYYY). This is an area statistic, not a rate or an individual property bill. Unsupported, missing and censored estimates are null.
place = parse.postal("28202", country="US", deep=True)
property_tax = (place.get("deep") or {}).get("property_tax")Read population as the source’s count for that place boundary. Keep missing or null values unknown and preserve a known zero. State district lists include each district’s population. Postal nearby and distance detail remains metropolitan associations only. Continent population stays in core.
Country deep includes land_area and water_area in km2, coastline in km, and elevation_average in meters. lowest_point and highest_point contain a nullable name and an elevation in metres. Values below sea level are negative. Missing or null values stay unknown, and zero stays zero.
Point returns the timezone ID with the core location. Its optional Deep adds terrain, compact nearest-city context and supported electoral detail on paid plans. Existing accounts retain their current Deep access. A nearest city is null when none is within 200 km.
Weather returns current conditions by default. Paid deep adds specialist current measurements, forecasts and related detail. On a paid plan, a past date adds history for that UTC day alongside current conditions in API 2.1. Earlier contracts require an explicit detail request.
parse.weather(40.7128, -74.006, deep=True, date="2026-08-15")Address search uses context from the form: prefer postal, or city and state. An optional end-user ip is a locality hint for server-side calls. An empty result explains itself with reason: more_input, missing_context or no_matches. With suggestions, reason is null. Older responses may omit it, and future reasons remain strings. Catalog and lookup failures use the existing API errors.
HLR reports status at the last check. live means assigned and connected means reachable at that check. Cached results may be returned. Null means unconfirmed. Deep diagnostics stay within the same metered lookup.
Bank inputs use POST /bank JSON bodies, keeping IBAN and account values out of request URLs. Pass original strings; the server owns normalization and validation. Avoid logging request bodies. IBAN deep can include directory with the immutable edition, resolved country and actual match grain (bank, branch, prefix or none); it is absent if no directory lookup ran. A match does not prove complete country coverage or payment reachability.
Call the API and get everything your plan includes. API 2.1 paid plans include their profile detail automatically; Free returns the complete everyday answer. Existing explicit deep options remain supported for compatibility. Mailbox verification is a separate explicit operation. An omitted or false SDK deep option follows the plan default; true remains an explicit compatibility request.
| Operation | Included data and explicit checks |
|---|---|
| IP | Richer IP fields included with a paid plan. No separate check meter. |
| Domain | Registration dates, registrar, status and DNSSEC, included with a paid plan. Use dns for DNS records and mx for mail routing. |
| Basic validation is separate. Call the explicit verification method for a metered mailbox check. | |
| Phone, Time, Date, Emoji, Point | Optional detail on paid plans in the same pooled request. Existing accounts retain their current Deep access. |
| Language | All language facts are in Core; Deep adds no fields. |
| Currency | Currency lookup facts are complete in Core; Deep adds no fields. Lookup and exchange-rate conversion use pooled requests. |
| Country, State, County, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
| Name, Industry | Name evidence or the industry definition profile on paid plans. |
| Company | The complete product detail bag on paid plans. |
| Weather | Specialist current measurements and the existing forecast, alert, air and history bag on paid plans. |
| Carrier, HLR | The selected metered operation returns its complete result by default. No deep option is required. |
Explicit Email verification includes mailbox status and the reason for the result, plus a suggested first name, no-reply flag, plus-address tag and mail service. The suggested name is not a verified identity. Unavailable details are null.
Reasons include accepted, invalid_format, invalid_domain, no_mail_server, mailbox_not_found, mailbox_disabled, mailbox_full, catchall, disposable, temporary_failure, rejected and unconfirmed.
Carrier, caller, and HLR are separate metered operations. Choose them explicitly when you need their answers. Ordinary lookups retry twice by default. Metered checks use one attempt by default. Setting retries explicitly can repeat paid usage.
With deep=true, available extra fields appear at their natural resource homes. Without it, or without access, those optional fields are absent. Included unknown values remain null; false and zero retain their meanings. There is no deep response object.
ip = parse.ip("52.94.76.10", deep=True)
ip.get("deep", {}).get("datacenter") # True, False, or NoneEvery non-2xx response raises ParseAPIError with status, code, docs, and request_id. Branch on code.
from parseapi import ParseAPIError
try:
parse.city("atlantis")
except ParseAPIError as err:
if err.code == "not_found":
... # no such cityNetwork and decoding failures keep their native error types. Responses such as valid: false are successful API answers, not exceptions.
parse = ParseAPI(
"your-api-key",
timeout=10.0, # timeout for each connect, read, write, or pool phase
)Requires Python 3.9 or later. One dependency (httpx).
Ordinary lookups retry network failures, 429, and 500/502/503/504 responses twice by default. Carrier, caller, HLR, and email with deep=True make one attempt by default. Address with deep=True also uses one attempt, reserving the same behavior for future verification.
An explicit client retries setting overrides those defaults; retries=0 always makes one attempt. Another attempt can consume additional usage if the earlier response was lost. Cancelling an async task stops the call and any retry wait. Automatic redirects are disabled.
Automatic retries wait at most five seconds per attempt. A longer valid Retry-After returns the original API error immediately without retrying early. Read retry_after on the error for the original header, or null when absent.
Full field reference for every endpoint: parseapi.com/docs
Send 2–11 leading digits as a string. Core returns bin, brand, brand_name
and a CDN SVG logo. Brand detection uses reviewed network rules independently
of issuer records. Unknown or ambiguous prefixes return null brand fields and a
generic logo; a known network without reviewed artwork also uses the generic logo.
Optional Deep adds prefix, issuer, country, type and prepaid on paid plans
in the same pooled request. Existing accounts retain their current Deep access.
Requested but locked Deep is {}. Six or more digits enable directory
matching. With Deep access, fewer digits return all-null Deep fields. Compare prefix with
bin: equal is an exact recorded match; shorter is broader; null is no match.
The longest row wins, including null fields. prepaid: null means unknown, not
false. This is partial reference data, not card validity or payment acceptance.
card = parse.card("51")
print(card["brand"], card["logo"])
details = parse.card("43737400", deep=True)
print(details.get("prefix"), details.get("issuer"))Leading zeros are preserved. Only ASCII spaces, tabs, CR, LF and hyphens are removed; raw input is limited to 64 characters. Invalid prefixes are rejected before dispatch, accepted input is forwarded unchanged. Never send a full card number.
The default response answers the common task. Ask for deep when you need more detail about that same result. Core fields stay equal. City, Company directory, Industry and Emoji searches put detail at the root of each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in to or each targets item; only the source has next_dst.
basic = parse.time("America/New_York")
detail = parse.time("America/New_York", deep=True)
print(basic["at"], detail.get("deep", {}).get("next_dst"))result = parse.stack("example.com")
# AsyncParseAPI exposes the same calls with await.Stack checks static homepage HTML and response headers. It returns the checked URL, original checked_at time and eight technology arrays.
cms, servers, frameworks, ecommerce, analytics, chat, payments and hosting are arrays because a site can use several technologies in each category. Each entry contains technology, name and nullable version. Technology codes are open strings. A successful check uses empty arrays for categories with no matches. When no HTML page could be checked, checked_at and all categories are null. Unknown or conflicting versions are null. Detections describe the checked homepage.
Successful checks may be reused for up to 24 hours. pretty optionally formats the wire JSON. Stack uses your plan's request allowance and API version 2.1.0 selected by this client.
Stack defaults to a 35-second transport timeout so a first scan has time to finish. Other lookups retain their 10-second default. An explicit client timeout takes precedence.
Resolve Unicode emoji or a named shortcode, search or browse a bounded catalog, parse emoji positions in text, and convert between Unicode and a selected shortcode source. The ordinary lookup remains four fields:
GET /emoji/rocket{"emoji":"🚀","name":"Rocket","shortcodes":[":rocket:","rocket"],"category":"Travel & Places"}Use deep=true for Unicode facts, keywords, tone families and available artwork.
Artwork is keyed by style: artwork.openmoji.svg is the SVG URL, and
artwork.openmoji.png["72"] is the 72×72 PNG URL (use your language’s map
access syntax). The same shape applies to noto and twemoji. Missing styles
and formats are omitted. URLs pin immutable artwork editions and retain their bytes.
Core values stay unchanged. Text parsing returns emojis with UTF-16 positions;
conversion returns text and unresolved tokens with positions and reasons.
The compact JSON catalog contains offline identity, qualification-form and
shortcode indexes. Use lang for localized names and keywords. Metadata and
shared source notices are included in the catalog. Read an individual emoji
with Deep for its artwork links. Artwork supports Google Noto, Twemoji
and OpenMoji, with real SVG/PNG availability and immutable first-party URLs.
A device's emoji font remains the ordinary display.
These additions are a local release candidate until the matching SDK and backend are published. Existing lookup and search contracts are preserved.
city = parse.city("Sakai", country="JP", state="27", grain="municipality",
aliases=True, ambiguity="error", hierarchy=True, deep=True)type selects the recorded country-specific place type. grain selects a reviewed municipality, subdivision, locality or metropolitan_area; unreviewed places do not match a grain filter. aliases=True enables reviewed name forms. ambiguity="error" rejects several eligible exact matches. Existing calls keep their defaults, and AsyncParseAPI accepts the same options.
hierarchy=True adds optional grain and parent fields using stable City IDs. A null parent means no relationship has been reviewed. Nearest lookup applies country, state, type and grain to eligible centers within 2,000 km; a nearest center does not establish boundary containment. Nearby type and grain select both the named anchor and its results.
Paid Deep can include population_observed_on and population_basis for a reviewed count at the same place layer. Download dates do not supply population observation dates. These options use current API 2.1.0; older responses can omit the new fields.
opts = dict(country="JP", min_population=100_000, sort="-population,+name",
limit=50)
first = parse.city.list(**opts)
for city in first["data"]:
print(city["id"], city.get("name"))
if first["next_cursor"]:
next_page = parse.city.list(**opts, cursor=first["next_cursor"])
parse.city.nearby_coordinates(48.2082, 16.3738, radius=40, unit="km")
parse.city.search("sa", page=True, timezone="Asia/Tokyo", bbox="130,30,145,45")Collections support inclusive min_population/max_population, min_elevation/max_elevation, countries, exclude_countries, timezones, exact timezone and center-coordinate bbox (west,south,east,north; west greater than east crosses the dateline). Unknown populations do not match a population range. Browse sorts by name or population; search also supports relevance; nearby also supports distance. order accepts asc or desc (relevance allows only asc); population defaults to descending with unknown counts last. Filtering and ordering use the same count as paid Deep.
lang="de" displays Vienna as Wien; lang="ja" supports 1,912 reviewed Japanese native names, and lang="zh-Hant" supports 377 reviewed Traditional Chinese names in Taiwan. Approved translations take precedence; missing or unsupported labels keep the source name. IDs and name_local stay unchanged. Name sorting uses the stored primary name, regardless of display language. Coordinate nearby defaults to 40 km, or 25 mi with unit="mi", and caps the radius at 800 km or 500 mi.
city.list and city.nearby_coordinates return { "object": "list", "data": [...], "next_cursor": ... }. Each item retains id and object: "city". Existing lookup, search, nearest and named-nearby calls keep their classic responses. Add format="list" to search or named nearby for a canonical collection, or format="resource" to lookup, ID lookup or nearest for a canonical resource. Classic search and named nearby include next_cursor with page=True or cursor; old responses may omit it. Keep the original options, including limit, when continuing. An invalid cursor or changed query/order returns 400; restart without the cursor. Pages are not a historical snapshot. Named nearby applies population, timezone and bbox to results, while country/state select its anchor. Async methods accept the same arguments.
city.children(id), city.ancestors(id) and city.siblings(id) return canonical lists with coverage: "partial". An empty list does not prove the absence of relatives. Children and siblings support page continuation. city.distance(from_id, to_id) returns object: "city_distance", from, to, distance in kilometers, distance_mi in miles and method: "great_circle". It compares stored centers; unknown coordinates remain null and known zero remains zero. Async clients support the same calls.
Strict ambiguity returns HTTP 409. Catch ParseAPIError with code == "ambiguous_city" and read optional error.candidates for at most two safe City identity objects; CityAmbiguityCandidate is exported as a TypedDict. Choose an ID or narrow the filters for a new request. Other errors and retry behavior remain unchanged.
Classic lookup, search, nearest and named-nearby methods retain their default envelopes and required-field models. Browse uses cities and coordinate-nearby uses nearby, with nullable next_cursor (camelCase properties in Swift/Kotlin). Keep all query options unchanged when continuing a page; no client fetches pages automatically.
page = parse.city.search('Viena', format='list', match='fuzzy', max_distance=1)Each route retains its default response. Country inclusion/exclusion sets, timezone sets, inclusive population and meter-elevation bounds, stored-center bbox and signed multi-key sorting are available for collections. Unknown numeric facts do not match range filters.
Search defaults to prefix matching. Exact and fuzzy matching are explicit; fuzzy accepts maximum edit distance 1 or 2 and returns match evidence (type, source, value, language, edit_distance). Review a fuzzy choice before storing its ID.
Reviewed children, ancestors and siblings use canonical lists with partial relationship coverage. Empty data does not prove there are no geographic relatives. Children/siblings accept page controls; ancestors do not. Distance reports great-circle kilometers and miles between stored centers: zero is known zero, null is unknown, and it does not imply travel time or containment.
Strict ambiguity=error can return HTTP 409 ambiguous_city with up to two safe candidate identities. The existing error constructor and unrelated error metadata are preserved; candidates are retained only for that status/code and never contain Deep. GeoJSON is available through HTTP; these typed City list methods do not return GeoJSON.
Reviewed name forms:
city = parse.city.id('city_7aj899nvwyku', format='resource', romanized=True)Coverage by country and available fields is described at https://parseapi.com/city#coverage.
romanized=true requests reviewed official name forms as name_romanized and romanization_language (camelCase in Swift/Kotlin). Current reviewed forms cover 20 Japanese whole-city aliases in ja-Latn. Missing or conflicting forms stay null; ASCII folding is not substituted for an official form.
Conditional If-None-Match reads and GeoJSON currently use HTTP directly. A matching City ETag returns 304 without a body; ordinary billing and rate limits apply. These JSON client methods do not supply conditional-cache handling.
IP paid Deep includes supported approximate location, state_name, postal, latitude, longitude, timezone, routed network, asn_type and public proxy status. Missing facts remain null. Coordinates describe range geography, not device GPS. asn_type classifies the origin network, not subscriber connection technology. Proxy/VPN false means unlisted. Optional fields are omitted without the requested detail or access.
Country and State capital coordinates use latitude and longitude. Update
capital.lat and capital.lon reads to capital.latitude and
capital.longitude when adopting this release.
API 2.1 Time returns the clock first and the matched place in location. Read that place directly; location.candidates is for unresolved choices. Unused resolution is absent. City matches keep the match kind, text and language without the source category or spelling score. Holiday JSON keeps scope and completeness without calendar hashes; explicitly selected work-profile pins remain.
This client targets ParseAPI 2.1.0. Upgrading requires response-reader changes: optional detail now lives on its resource. Read population instead of deep.population. Deep remains an explicit request for optional detail. Without the request or access, optional fields are absent. A returned null still means unknown. User-Agent device, OS and browser are objects in every mode. Postal tax is one tax object. Specialist Weather measurements live in current. Metered Carrier and HLR return the complete purchased result without a Deep switch.
Use parse.email_verify(email) (sync and async) for mailbox verification. It sends POST /email/verify with { "email": "person@example.com" } and defaults to no automatic retries. The earlier Email deep argument is accepted only as a migration alias for that same operation. App keys receive permission_denied. Bulk exports retain their existing column names and saved-job recovery.
The 2.0 API is a temporary migration bridge for older installed clients. There is one maintained SDK line using the 2.1 structure.
This version selects API 2.1.0. Update existing .deep property reads to the fields at their natural homes, such as country.population. User-Agent identities are objects; Postal tax and Weather observations keep their documented object homes. Paid plans include their profile detail automatically in API 2.1. Free keeps its complete routine answer, and existing explicit deep options remain supported. Mailbox verification stays explicit.
This minor version changes existing field reads. Upgrade the SDK and your application reads together. Existing factories remain. Email verification is explicit and includes basic validation; Carrier/HLR need no extra detail request. Preserve missing values, null, false and 0.
This source selects HTTP API 2.2.0. County is the public name for counties and comparable administrative areas internationally. Use county and the State counties operation. Read county, county_name, county_name_local and counties in affected geography results; City capital_of uses county for this administrative level. Actual local types such as department and district retain their meaning.
This is a breaking field-read upgrade from earlier contracts. Deprecated District callable names remain source aliases, but SDK results use the canonical County fields. Update property reads before upgrading. Older installed packages keep their existing API contract, and this client does not change an account's saved default.