Postal Codes

The Postal Codes GraphQL API provides access to postal code data including geographic coordinates, country/state associations, and automatic time zone resolution from GPS coordinates.

Overview

• Entity: postalCode
• Queries: Single lookup by ID, paginated list with search/filter/sort
• Time Zone Resolution: Automatically resolves time zone from latitude/longitude when not stored
• Search: By postal code or place name (case-insensitive)

GraphQL Schema

Types

postalCode

type postalCode {
  id: Int!
  accuracy: AccuracyTypes
  code: String!
  countryCode: String!
  country: country!
  created: DateTime!
  createdBy: String!
  customValues: Map
  lastModified: DateTime!
  lastModifiedBy: String!
  location: [Float]
  longitude: Float
  latitude: Float
  organizationId: Int!
  placeName: String!
  stateCode: String
  timeZone: String
  state: state
  updatedUser: user!
  createdUser: user!
}

Key fields:

Field	Type	Description
code	String!	The postal/ZIP code
placeName	String!	City or locality name
countryCode	String!	ISO country code
stateCode	String	State/province code
latitude	Float	GPS latitude coordinate
longitude	Float	GPS longitude coordinate
location	[Float]	Raw coordinate array [longitude, latitude]
timeZone	String	IANA time zone identifier (e.g., America/New_York) — resolved automatically from coordinates if not stored
accuracy	AccuracyTypes	Geocoding accuracy level
customValues	Map	Custom key-value data
country	country!	Related country entity
state	state	Related state/province entity

Time Zone Resolution

The timeZone field uses a smart resolver that:

1. Returns the stored time zone if one exists on the postal code record
2. Otherwise, computes the time zone from the latitude and longitude coordinates using GPS-based lookup
3. Returns null if no stored time zone exists and coordinates are unavailable

This means you can always request timeZone and get a resolved value for any postal code that has GPS coordinates, even if the time zone was never explicitly stored.

Queries

Get Single Postal Code

Retrieve a specific postal code by ID.

query {
  postalCode(
    organizationId: 1
    id: 456
  ) {
    id
    code
    placeName
    countryCode
    stateCode
    latitude
    longitude
    timeZone
    country {
      name
    }
    state {
      name
    }
  }
}

List Postal Codes

Retrieve a paginated list of postal codes with optional search, filter, and sort.

query {
  postalCodes(
    organizationId: 1
    search: "9001"
    orderBy: "code asc"
    skip: 0
    take: 25
  ) {
    items {
      id
      code
      placeName
      countryCode
      latitude
      longitude
      timeZone
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
    totalCount
  }
}

Parameters:

Parameter	Required	Description
organizationId	Yes	Organization ID
search	No	Search by postal code or place name (case-insensitive, partial match)
filter	No	Filter expression
orderBy	No	Sort order (e.g., "code asc", "placeName desc")
skip	No	Number of items to skip for pagination
take	No	Number of items to return

Example: Look Up Time Zone for a Postal Code

query {
  postalCodes(
    organizationId: 1
    search: "10001"
  ) {
    items {
      code
      placeName
      timeZone
      latitude
      longitude
    }
  }
}

Response:

{
  "data": {
    "postalCodes": {
      "items": [
        {
          "code": "10001",
          "placeName": "New York",
          "timeZone": "America/New_York",
          "latitude": 40.7484,
          "longitude": -73.9967
        }
      ]
    }
  }
}

Related Topics

• GraphQL API Overview