Address

A physical address serves as a precise and official location identifier for a building or residence. It follows a standardized format that incorporates various elements.

The significance of a physical address is multifaceted. It underpins essential aspects of daily life and business operations. Entities rely on physical addresses for official correspondence, service delivery, and verification purposes. An official address ensures you receive important documents, can register for utilities, and establish residency.

More about Addresses on Wikipedia →

Model

Specific structure of the data that represents the entity within the API. It defines the attributes and their data types associated with the entity.

It's important to note that you'll need to retrieve the complete identifier for an entity each time you require its complete model. This can be achieved by utilizing the find endpoint to locate the entity and then using the retrieved identifier to call the retrieve endpoint for complete model.

This API prioritizes efficient data transmission and minimizes response sizes. While the retrieve endpoint provides the complete data model for a requested entity, it adheres to the principle of "sparse representation." This means that certain properties within the model might be omitted if they lack any relevant data for the specific entity.

  • Name
    id
    Type
    string
  • Name
    formatted
    Type
    string
  • Name
    lot
    Type
    object
    Description
    • Name
      prefix
      Type
      string
    • Name
      number
      Type
      string
    • Name
      suffix
      Type
      string
  • Name
    flat
    Type
    object
    Description
    • Name
      type
      Type
      string
    • Name
      numberPrefix
      Type
      string
    • Name
      number
      Type
      string
    • Name
      numberSuffix
      Type
      string
  • Name
    level
    Type
    object
    Description
    • Name
      indicator
      Type
      string
    • Name
      numberPrefix
      Type
      string
    • Name
      number
      Type
      string
    • Name
      numberSuffix
      Type
      string
  • Name
    number
    Type
    object
    Description
    • Name
      firstPrefix
      Type
      string
    • Name
      first
      Type
      string
    • Name
      firstSuffix
      Type
      string
    • Name
      lastPrefix
      Type
      string
    • Name
      last
      Type
      string
    • Name
      lastSuffix
      Type
      string
  • Name
    street
    Type
    object
    Description
    • Name
      name
      Type
      string
    • Name
      type
      Type
      string
    • Name
      typeSuffix
      Type
      string
  • Name
    building
    Type
    string
  • Name
    locality
    Type
    string
  • Name
    city
    Type
    string
  • Name
    state
    Type
    string
  • Name
    postcode
    Type
    string
  • Name
    country
    Type
    string
  • Name
    latitude
    Type
    string
  • Name
    depth
    Type
    string
GET/geo/address/find/

Find

This API endpoint utilizes a full-text search functionality to help you locate entities that match with your search criteria. By providing a query, system will scan through all available data, pinpointing all entities that contain relevant keywords or phrases.

The find endpoint performs full-text search across the following field: formatted.

This API endpoint prioritizes speed and efficiency by returning a partial model with a limited set of properties for each matching entity. To retrieve the complete entity details, you can leverage retrieve API endpoint designed for specific entity retrieval based on unique identifiers.

Mandatory headers

  • Name
    x-api-key
    Type
    string
    Description
    A valid API key obtained through active subscription must be included in the header in order for the endpoint to work.

Mandatory attributes

  • Name
    country
    Type
    string
    Description
    By including this attribute, you can specify which dataset (Australia or New Zealand) you want to search. Valid values for this attribute are au for Australian dataset (Default) and nz for New Zealand dataset.
  • Name
    query
    Type
    string
    Description
    This mandatory attribute represents the search query you wish to execute. The query string must be at least three characters long for the search to function effectively.

Optional attributes

  • Name
    offset
    Type
    integer
    Description
    Pagination is implemented to manage potentially large result sets. This optional parameter allows you to specify the number of entities to skip before retrieving the desired page of results.

Request

GET
/geo/address/find/
curl "https://api.vigil.sh/geo/address/find/?country={country}&query={query}" \
  -H 'x-api-key: {api-key}'

Response

{
  "results": [
    {
      "id": "_tWP_z8_c2ZWh13rwhzGxT1ht-nWFVCnWA==",
      "formatted": "100 GEORGE STREET, SYDNEY NSW 2000"
    },
    // ...
  ],
  "resultsTotal": 189
}
GET/geo/address/locate/

Locate

This API endpoint utilizes a geospatial search functionality to help you locate entities that match with your search criteria. By providing a latitude, longitude and query, system will scan through all available data using geospatial data, pinpointing all entities that contain relevant keywords or phrases. Distance searches are limited to 50,000 meters (50km) maximum radius. Requests with larger distances will be automatically capped at this limit.

This API endpoint prioritizes speed and efficiency by returning a partial model with a limited set of properties for each matching entity. To retrieve the complete entity details, you can leverage retrieve API endpoint designed for specific entity retrieval based on unique identifiers.

Mandatory headers

  • Name
    x-api-key
    Type
    string
    Description
    A valid API key obtained through active subscription must be included in the header in order for the endpoint to work.

Mandatory attributes

  • Name
    country
    Type
    string
    Description
    By including this attribute, you can specify which dataset (Australia or New Zealand) you want to search. Valid values for this attribute are au for Australian dataset (Default) and nz for New Zealand dataset.
  • Name
    lat
    Type
    float
    Description
    This mandatory attribute represents the north-south position of a location. Ranges from -90° at the South Pole to +90° at the North Pole. Values with a north designation (positive) indicate locations further north from the equator, while negative values (south) signify locations south of the equator.
  • Name
    lon
    Type
    float
    Description
    This mandatory attribute represents the east-west position of a location. Ranges from -180° to +180°. The Prime Meridian (0° longitude) runs through Greenwich, England, and serves as the reference point for east and west. Positive values (east) indicate locations further east of the Prime Meridian, while negative values (west) signify locations west of it.
  • Name
    distance
    Type
    integer
    Description
    This mandatory attribute represents the actual physical separation between two points on the Earth's surface. Using latitude and longitude coordinates, entities will be located within the given distance.
  • Name
    query
    Type
    string
    Description
    This mandatory attribute represents the search query you wish to execute. The query string must be at least three characters long for the search to function effectively.

Optional attributes

  • Name
    offset
    Type
    integer
    Description
    Pagination is implemented to manage potentially large result sets. This optional parameter allows you to specify the number of entities to skip before retrieving the desired page of results.

Request

GET
/geo/address/locate/
curl "https://api.vigil.sh/geo/address/locate/?country={country}&lat={lat}&lon={lon}&distance={distance}&query={query}" \
-H 'x-api-key: {api-key}'

Response

{
  "id": "x9fcoyB9c2ZWh13rwhzGxVDPl0jPV08bPQ==",
  "formatted": "100 GEORGE STREET, SYDNEY NSW 2000",
  "distance": 22
}
GET/geo/address/

Retrieve

This API endpoint utilizes a data retrieval functionality to help you access the entity associated with a provided unique identifier. When you provide a unique identifier, the system scans through all available data in order to pinpoint the exact entity that matches that identifier.

This API endpoint prioritizes the integrity and comprehensiveness of your data by returning the complete data model with the entire set of properties for the matching entity. To find the different entity, you can leverage find API endpoint designed for full-text search based on your query.

Mandatory headers

  • Name
    x-api-key
    Type
    string
    Description
    A valid API key obtained through active subscription must be included in the header in order for the endpoint to work.

Mandatory attributes

  • Name
    country
    Type
    string
    Description
    By including this attribute, you can specify which dataset (Australia or New Zealand) you want to search. Valid values for this attribute are au for Australian dataset (Default) and nz for New Zealand dataset.
  • Name
    id
    Type
    string
    Description
    This mandatory attribute represents the unique identifier associated with specific entity. The unique identifiers used within this API are not static values. Instead, they employ a rotation mechanism, meaning they change frequently, often with nearly every request.

Request

GET
/geo/address/
curl "https://api.vigil.sh/geo/address/?country={country}&id={id}" \
  -H 'x-api-key: {api-key}'

Response

{
  "formatted": "100 GEORGE STREET, SYDNEY NSW 2000",
  "lot": {},
  "flat": {
    "type": "SHOP",
    "number": "1"
  },
  "level": {},
  "number": {
    "first": "100"
  },
  "street": {
    "name": "GEORGE",
    "type": "STREET"
  },
  "building": "",
  "locality": "SYDNEY",
  "state": "NSW",
  "postcode": "2000",
  "country": "AU",
  "depth": "S"
}