docs / geo-postal

Postal Code & Geocoding API

base /geo-postal/v111 endpoints

post/geo-postal/v1/eu_regions2 credits

Coordinates OR postal code → EU/EFTA/candidate statistical regions: country, NUTS 0-3 hierarchy, LAU commune (GISCO NUTS-2024 + LAU-2024 + TERCET pc2025).

Parameter		Allowed / range	Description
lat	optional	-90–90	WGS84 latitude of the point to resolve (decimal degrees).
lon	optional	-180–180	WGS84 longitude of the point to resolve (decimal degrees).
postal_code	optional	—	Postal code to resolve. Spaces/dashes are ignored, case-insensitive (e.g. '10115', '75001', 'SW1A1AA').
country	optional	—	ISO-3166 alpha-2 country code (e.g. DE, FR, TR, IN, US). Greece accepts GR or EL.
include_geometry = false	optional	—	If true, include the (simplified) boundary polygon as GeoJSON. Default false — geometries are large; lookups never depend on this.

Try in playground →

post/geo-postal/v1/tr_regions2 credits

Türkiye: koordinat, posta kodu VEYA il/ilçe/mahalle adı → resmî idari hiyerarşi (il+plaka, ilçe, mahalle/köy, posta kodları) + NUTS-TR istatistik kodları.

Parameter		Allowed / range	Description
lat	optional	-90–90	WGS84 latitude of the point to resolve (decimal degrees).
lon	optional	-180–180	WGS84 longitude of the point to resolve (decimal degrees).
postal_code	optional	—	Postal code to resolve. Spaces/dashes are ignored, case-insensitive (e.g. '10115', '75001', 'SW1A1AA').
province	optional	—	Province (il) name, e.g. İstanbul, Ankara, İzmir. Turkish characters optional (istanbul works).
district	optional	—	District (ilçe) name within the province.
neighborhood	optional	—	Neighborhood (mahalle) or village (köy) name.
include_geometry = false	optional	—	If true, include the (simplified) boundary polygon as GeoJSON. Default false — geometries are large; lookups never depend on this.

Try in playground →

post/geo-postal/v1/in_postal2 credits

India: PIN code OR post-office name → post offices, district, state, lat/lon centroid (official All-India Pincode Directory).

Parameter		Allowed / range	Description
pincode	optional	—	6-digit Indian PIN code, e.g. 400001 (Mumbai GPO).
office	optional	—	Post-office name to search (exact or prefix), when the PIN is unknown.
state	optional	—	Optional state filter for office search.
district	optional	—	Optional district filter for office search.

Try in playground →

post/geo-postal/v1/us_regions2 credits

United States: ZIP code OR coordinates → state, county + 5-digit county FIPS, place, ZIP centroid, and the CGAZ state/county boundary. Built WITHOUT census.gov (GeoNames ZIP directory carries county FIPS; ANSI state-FIPS is a public-domain constant). For census-grade ZCTA + tract/block GEOIDs use the `us_census` action (TIGER/ZCTA polygons + Census Geocoder, gov-pending/91).

Parameter		Allowed / range	Description
postal_code	optional	—	Postal code to resolve. Spaces/dashes are ignored, case-insensitive (e.g. '10115', '75001', 'SW1A1AA').
lat	optional	-90–90	WGS84 latitude of the point to resolve (decimal degrees).
lon	optional	-180–180	WGS84 longitude of the point to resolve (decimal degrees).
include_geometry = false	optional	—	If true, include the (simplified) boundary polygon as GeoJSON. Default false — geometries are large; lookups never depend on this.

Try in playground →

post/geo-postal/v1/us_census3 credits

United States census-grade geocode: street ADDRESS, ZIP, or coordinates → state, county (+5-digit FIPS), census TRACT GEOID, census BLOCK GEOID, ZCTA, and tract/ZCTA land-area — with match_type + confidence. Coordinates/ZIP resolve the ZCTA offline from pinned TIGER/ZCTA-2024 polygons (zero egress); the authoritative tract/block GEOID + address geocoding come from the US Census Geocoder, cached. US-Gov public domain (Title 17 §105).

Parameter		Allowed / range	Description
address	optional	—	One-line US street address to geocode to its census tract/block (uses the Census Geocoder; rooftop interpolation, not a deliverability/CASS claim).
postal_code	optional	—	Postal code to resolve. Spaces/dashes are ignored, case-insensitive (e.g. '10115', '75001', 'SW1A1AA').
lat	optional	-90–90	WGS84 latitude of the point to resolve (decimal degrees).
lon	optional	-180–180	WGS84 longitude of the point to resolve (decimal degrees).
include_geometry = false	optional	—	If true, include the (simplified) boundary polygon as GeoJSON. Default false — geometries are large; lookups never depend on this.
live = true	optional	—	If true (default) and an exact tract/block GEOID is needed, query the Census Geocoder (cached). Set false for offline-only (ZCTA polygon + nearest-tract centroid) with no .gov call.

Try in playground →

post/geo-postal/v1/admin_boundary2 credits

GLOBAL coordinates → administrative boundary hierarchy ADM0/ADM1/ADM2 (geoBoundaries CGAZ composite, CC-BY 4.0).

Parameter		Allowed / range	Description
lat	required	-90–90	WGS84 latitude of the point to resolve (decimal degrees).
lon	required	-180–180	WGS84 longitude of the point to resolve (decimal degrees).
levels = 0,1,2	optional	—	Comma-separated geoBoundaries levels to resolve: 0 (country), 1 (state/region), 2 (county/municipality). Default all three.
include_geometry = false	optional	—	If true, include the (simplified) boundary polygon as GeoJSON. Default false — geometries are large; lookups never depend on this.

Try in playground →

post/geo-postal/v1/postal_lookup1 credit

country + postal code → region metadata for ~100 countries (GeoNames postal directory) with country-specific enrichment (EU→NUTS3, TR→mahalle, IN→offices).

Parameter		Allowed / range	Description
country	required	—	ISO-3166 alpha-2 country code (e.g. DE, FR, TR, IN, US). Greece accepts GR or EL.
postal_code	required	—	Postal code to resolve. Spaces/dashes are ignored, case-insensitive (e.g. '10115', '75001', 'SW1A1AA').

Try in playground →

post/geo-postal/v1/postal_search1 credit

country + city/place → its postal codes (zip-by-city); country + admin1 only → that state's codes (zip-by-state); country only → the country's states/regions list (GeoNames directory).

Parameter		Allowed / range	Description
country	required	—	ISO-3166 alpha-2 country code (e.g. DE, FR, TR, IN, US). Greece accepts GR or EL.
place	optional	—	Place/city name to list postal codes for. Accent and case-insensitive (munchen finds München). Omit it and pass only admin1 for a state-wide listing; omit both for the country's admin-1 (state/region) list.
admin1	optional	—	Optional admin-1 (state/region) filter, name or code.
limit = 50	optional	1–100	Max codes to return (1-100, default 50).

Try in playground →

post/geo-postal/v1/postal_distance1 credit

Great-circle distance between two postal codes (same or different countries).

Parameter		Allowed / range	Description
country	required	—	ISO-3166 alpha-2 country code (e.g. DE, FR, TR, IN, US). Greece accepts GR or EL.
from	required	—	Origin postal code (in `country`).
to	required	—	Destination postal code (in `to_country`, default same country).
to_country	optional	—	Destination ISO-3166 alpha-2 country if different.
unit = km	optional	km · mi	Distance unit (km default, mi).

Try in playground →

post/geo-postal/v1/postal_radius1 credit

All postal codes within a radius of a postal code (centroid-based).

Parameter		Allowed / range	Description
country	required	—	ISO-3166 alpha-2 country code (e.g. DE, FR, TR, IN, US). Greece accepts GR or EL.
postal_code	required	—	Postal code to resolve. Spaces/dashes are ignored, case-insensitive (e.g. '10115', '75001', 'SW1A1AA').
radius_km	required	0.1–100	Search radius in kilometres (0.1-100).
limit = 50	optional	1–100	Max codes to return, nearest first (1-100).

Try in playground →

post/geo-postal/v1/batch2 credits

Resolve up to 50 mixed lookups in one call (cheap local queries).

Parameter		Allowed / range	Description
items	required	—	Up to 50 lookup items. Each is an object with an `action` (eu_regions\|tr_regions\|in_postal\|admin_boundary\|postal_lookup) plus that action's params. Items resolve independently — one bad item never fails the batch.

Try in playground →

Example request · eu_regions

curl -X POST https://api.reefapi.com/geo-postal/v1/eu_regions \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"lat":52.52,"lon":13.405}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}