1. Addresses
  2. GeoCode

Addresses

GeoCode

The Address Geocoding API converts addresses into geographical coordinates (latitude and longitude), supporting multiple input formats.

POST
`/v1/address/beta/geocode`

Request Methods

Address String Format

For simple string-based address inputs:

js 
        const data = {
  address: "500 7th Ave, New York, NY 10018",
};

fetch(`https://api.packagex.io/v1/address/beta/geocode`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

Address Object Format

For structured address data:

js 
        const data = {
  address: {
    line1: "500 7th Ave",
    line2: "Floor 10",
    city: "New York",
    state: "NY",
    postal_code: "10018",
  },
};

fetch(`https://api.packagex.io/v1/address/beta/geocode`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

Existing Address / Location Format

For existing PackageX addresses or locations:

js 
        const data = {
  address: "addr_11fkZ8wQzscUj9SZaX1By1"
  // OR
  address: "loc_jZ1fYiQobeWthjbhme3vDX"
};

fetch(`https://api.packagex.io/v1/address/beta/geocode`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

Response Format

The API returns coordinates in a standardized format:

js 
        {
    "message": "Coordinates parsed successfully",
    "data": [40.75322269999999, -73.9892675],
    "status": 200,
    "errors": [],
    "code": null,
    "pagination": null,
    "endpoint": null
}

Error Scenarios

The API provides specific error responses for various failure cases:

  • Missing address
js 
        {
  "message": "Please provide an address or coordinates to parse",
  "data": {},
  "status": 400,
  "errors": [],
  "code": "address.parse_failed",
  "pagination": null,
  "endpoint": null
}
  • When the API cannot successfully parse an address
js 
        {
  "message": "We cannot parse this address",
  "data": {},
  "status": 500,
  "errors": [],
  "code": "address.parse_failed",
  "pagination": null,
  "endpoint": null
}

Reverse GeoCode

This endpoint converts geographic coordinates (latitude and longitude) into a structured address. The system first checks for existing addresses in the database before performing a new geocoding operation.

POST
`/v1/address/beta/reverse-geocode`

Required Parameters

Parameter Type Description
coordinates [number, number] Array containing latitude and longitude in decimal format

Optional Parameters

Parameter Type Default Description
verify boolean false Whether to verify the parsed address.

Request Example

js 
        const data = {
  coordinates: [33.3820989, -111.964918], // [latitude, longitude]
  verify: true,                           // Optional
};

const response = await fetch(`https://api.packagex.io/beta/reverse-geocode`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

Response Format

The API returns coordinates in a structured format:

js 
        {
    "message": "Address parsed successfully",
    "data": {
        "object": "address",
        "id": "addr_123",
        "uuid": "1LkceNKqeHEbMrxpasdad",
        "line1": "5000 S Arizona Mills Cir",
        "line2": "5000 S Arizona Mls Cir, Tempe, Az 85282, United States",
        "city": "Tempe",
        "country": "United States",
        "country_code": "US",
        "formatted_address": "5000 S Arizona Mills Cir, 5000 S Arizona Mls Cir, Tempe, Az 85282, United States, Tempe, AZ 85282, United States",
        "postal_code": "85282",
        "state": "Arizona",
        "state_code": "AZ",
        "textarea": "5000 S Arizona Mills Cir \rTempe, AZ 85282\rUnited States",
        "timezone": "America/Phoenix",
        "verified": false,
        "coordinates": [
            33.3820989,
            -111.964918
        ],
        "hash": "cMnMM8Ve6zURtec83oKtMN"
    },
    "status": 200,
    "errors": [],
    "code": null,
    "pagination": null,
    "endpoint": null
}

Error Scenarios

  • When the API cannot successfully parse coordinates
js 
        {
  "message": "We cannot parse this address",
  "data": {},
  "status": 500,
  "errors": [],
  "code": "address.parse_failed",
  "pagination": null,
  "endpoint": null
}
Previous <- Parse
Next Analytics Overview ->