parseapi

Official ParseAPI client for Python.

pip install parseapi

from 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.

API versions

Version 1.7.0 explicitly selects the API contract supported by this SDK. It sends Parse-Version: 2.0.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.

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.

Previously published SDKs keep their existing behavior and use the team's default. Requests without Parse-Version also 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 Parse-Version header selects a supported contract. See API versions and migration.

Weather from a postal code

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.

Supply the context you know

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. deep.tax names the levy and deep.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. Country deep.tax_id_format and deep.tax_id_regex describe registration-number format only. Use vat for a metered registration check with deep explicitly enabled.

Calls

One method per endpoint, named after the route.

parse.ip("8.8.8.8")
parse.ip.self()
parse.email("hello@gmail.com")
parse.vat("DE136695976")
parse.iban("DE89370400440532013000")
parse.bin("424242")
parse.npi("1881018208")
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.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.districts("NC", country="US")
parse.district("37081")
parse.continent("NA")
parse.continent.countries("NA")
parse.bloc("EU")
parse.bloc.countries("EU")
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.mac("00:1B:63:84:45:E6")
parse.mx("example.com")
parse.dns("example.com")
parse.dns("_dmarc.example.com", type="TXT")
parse.useragent(ua_string)
parse.vin("1HGCM82633A004352")
parse.naics("541511")
parse.naics.search("coffee shop", limit=5)
parse.tariff("8471.30.01.00")
parse.tariff.search("sunglasses")
parse.emoji("rocket")
parse.emoji.search("fire")

NAICS paid deep records include classification deep.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.

Async

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 and salutation. 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.

Display language

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, and unit discovery. IP, ASN, Company and NPI 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 and measurement locale remain explicit input-parsing controls.

Time

time returns local ISO at with its UTC offset and integer Unix seconds in unix. The core offset preserves exact precision. Optional deep.offset_seconds gives the numeric offset, while deep.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.

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:00

Canonical Time deep includes the pinned rule edition in deep.timezone_database_version and source-wall resolution in deep.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 have null 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'])

Location inputs and timezone filters

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.

Measurements

result = parse.measure("5 ft 11 in", to="cm")
units = parse.measure.units(unit="m")

amount is a decimal string, such as "180.34". Without to, the API returns the canonical unit for the measurement type. Pass locale for number formatting and system (us or imperial) when a customary unit needs context. Ambiguous input returns valid: false, a reason, and available choices. Invalid or incompatible target units use the normal API error.

Unit discovery accepts optional query, type, and unit filters. unit selects compatible targets. Omit the filters for the reviewed catalog. Both operations use pooled requests.

Place statistics and optional detail

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 and District paid profiles include deep.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_period alongside population: a reporting year (YYYY) or period (YYYY-YYYY), null when unknown or unverifiable. Keep missing or null values unknown and preserve a known zero. These fields belong to full place profiles. State district lists include each district's population and period. 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 mean elevation in metres. 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 detail adds terrain and compact nearest-city context on every plan. 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. A past date is a UTC day and requires deep: it adds deep.history alongside current conditions. Date alone does not request history.

parse.weather(40.7128, -74.006, deep=True, date="2026-08-15")

Tariff starts with the general schedule line. Paid deep adds units and the special and other schedule columns. An optional origin then resolves country-specific measures. The three calls below show those successive choices. Without origin, schedule detail is still returned and origin-dependent fields are null. A null effective rate is not a zero rate.

Tariff lookup and search accept an optional edition fingerprint and date (YYYY-MM-DD). The edition pins exact immutable source bytes. A date is accepted only when verified source coverage exists. An edition without a date returns undated schedule context (date: null). Default requests use today. Paid detail exposes an open-string reason when effective_rate is null, including incomplete_coverage. A null rate never means zero. Explicit selections fail with tariff_selection_mismatch if an older server ignores the requested scope.

Origin means where the goods originate, not where they ship from. The effective rate covers matched stored schedule measures only. It is not complete duty or landed cost.

Codes contain 4, 6, 8 or 10 ASCII digits; dots and whitespace are optional. Search returns up to 20 description matches with parent lineage so a result named "Other" has context. Search is not product classification. In deep, measures: null means origin-dependent measures were not resolved. measures: [] means the resolved lookup found none.

parse.tariff("8471.30.01.00")
parse.tariff("8471.30.01.00", deep=True)
parse.tariff("8471.30.01.00", deep=True, origin="CN")

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.

Deep

Choose enrichment for the question you need answered.

Email deep 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.

Without deep, the response omits that key. When requested, it is an empty object if access is locked or the operation has no deep fields. Otherwise it contains the available fields. A missing or null field means unknown.

ip = parse.ip("52.94.76.10", deep=True)
ip.get("deep", {}).get("datacenter")  # True, False, or None

Errors

Every 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 city

Network and decoding failures keep their native error types. Responses such as valid: false are successful API answers, not exceptions.

Options

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 or VAT 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.

Docs

Full field reference for every endpoint: parseapi.com/docs

BIN lookup accepts 6-11 digits as a string, including leading zeros. Spaces and hyphens are accepted. prefix is the actual longest match and can be shorter than the input. Unknown reference fields are null. deep adds an empty object on every plan.

Optional detail

The default response answers the common task. Ask for deep when you need more detail about that same result. Core fields stay equal. City, NAICS and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in to.deep; only the source has deep.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"))

Stack API

result = parse.stack("example.com")
# AsyncParseAPI exposes the same calls with await.

Pass a public hostname without a scheme, path, port or IP address. Stack returns the checked URL and checked_at time, followed by scope, pages and partial. scope is homepage or site; pages counts successfully checked HTML pages. partial is true for homepage-only or incomplete bounded site checks. False means the known in-scope candidates were completed, not that every page on a website was visited. A homepage result has scope: "homepage", pages: 1 and partial: true.

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, pages is 0 and partial is null. Unknown or conflicting versions are null. Missing detections do not prove absence.

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.0.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.