> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.goshippo.com/feedback
```json
{
"path": "/api-reference/address-book/retrieve-addresses",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Retrieve addresses
> Returns a list of addresses based on search criteria
## OpenAPI
````yaml /api-reference/addressesapi/address_v2.yaml get /v2/addresses
openapi: 3.1.0
info:
title: Shippo Address API
summary: The Shippo Address API
description: >-
Address book, Address validation, and Address parsing
[https://goshippo.com](https://goshippo.com/)
x-logo:
url: https://docs.goshippo.com/images/shippo-logo.svg
contact:
name: Shippo Support
url: https://support.goshippo.com/hc
email: support@shippo.zendesk.com
version: '0.1'
servers:
- url: https://api.goshippo.com
security: []
tags:
- name: Address Book
description: Store, retrieve, modify, and delete your address book contacts
- name: Validation
description: Check your address is valid before creating shipping labels
- name: Parser
description: Convert address strings into a correctly formatted address object
paths:
/v2/addresses:
get:
tags:
- Address Book
summary: Retrieve addresses
description: Returns a list of addresses based on search criteria
operationId: get_addresses_addresses_get
parameters:
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
default: 30
title: Limit
- name: search
in: query
required: false
schema:
type: string
title: Search
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AddressesResponse'
'422':
content:
application/json:
example:
detail:
- type: greater_than_equal
loc:
- query
- limit
msg: Input should be greater than or equal to 1
input: '0'
ctx:
ge: 1
url: https://errors.pydantic.dev/2.3/v/greater_than_equal
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
5XX:
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Server Error
security:
- Shippo_Token: []
x-codeSamples:
- lang: cURL
label: curl
source: >-
curl -i -X GET \
'https://api.goshippo.com/v2/addresses?offset=0&limit=30&search=string'
\
-H 'Authorization: ShippoToken '
components:
schemas:
AddressesResponse:
properties:
offset:
anyOf:
- type: integer
- type: 'null'
title: Offset
example: 1
limit:
anyOf:
- type: integer
- type: 'null'
title: Limit
example: 1
count:
type: integer
title: Count
example: 1
next:
anyOf:
- type: string
- type: 'null'
title: Next
example: /addresses?offset=2&limit=1
prev:
anyOf:
- type: string
- type: 'null'
title: Prev
example: /addresses?offset=0&limit=1
results:
items:
$ref: '#/components/schemas/AddressWithMetadata'
type: array
title: Results
type: object
required:
- count
- results
title: AddressesResponse
UnprocessableEntityResponse:
properties:
detail:
items:
$ref: '#/components/schemas/ErrorDetail'
type: array
title: Detail
description: Details of the issue with the request.
type: object
required:
- detail
title: UnprocessableEntityResponse
description: A response for invalid requests with details of the issue.
InternalServerErrorResponse:
properties:
message:
type: string
title: Message
description: The error message for an internal server error
default: Internal Server Error
trace_id:
type: string
title: Trace Id
description: >-
The OpenTelemetry trace identifier that is unique to the request. A
valid trace identifier is a 16-byte array with at least one non-zero
byte
example: b562cab2e9200ac3e11474cc877580e1
type: object
required:
- trace_id
title: InternalServerErrorResponse
AddressWithMetadata:
properties:
id:
type: string
title: Id
example: e9f1f6fd20f84982afe471ff06c5a80f
address:
$ref: '#/components/schemas/Address'
updated_at:
type: string
format: date-time
title: Updated At
created_at:
type: string
format: date-time
title: Created At
type: object
required:
- id
- address
- updated_at
- created_at
title: AddressWithMetadata
ErrorDetail:
properties:
type:
type: string
title: Type
description: The type of error
examples:
- missing
loc:
items:
type: string
type: array
title: Loc
description: The location of the error
examples:
- - query
- country_code
msg:
type: string
title: Msg
description: The error message
examples:
- Field required
input:
anyOf:
- {}
- type: 'null'
title: Input
description: The input values for this field
examples:
- 'null'
type: object
required:
- type
- loc
- msg
title: ErrorDetail
Address:
properties:
name:
type: string
title: Name
example: Wilson
email:
anyOf:
- type: string
format: email
- type: 'null'
title: Email
example: user@shippo.com
phone:
anyOf:
- type: string
- type: 'null'
title: Phone
example: +1-4155550132
organization:
anyOf:
- type: string
- type: 'null'
title: Organization
example: Shippo
address_line_1:
type: string
title: Address Line 1
example: 731 Market Street
address_line_2:
anyOf:
- type: string
- type: 'null'
title: Address Line 2
example: '#200'
city_locality:
anyOf:
- type: string
- type: 'null'
title: City Locality
example: San Francisco
state_province:
anyOf:
- type: string
- type: 'null'
title: State Province
example: CA
postal_code:
anyOf:
- type: string
- type: 'null'
title: Postal Code
example: '94103'
country_code:
type: string
title: Country Code
example: US
address_type:
allOf:
- $ref: '#/components/schemas/AddressType'
default: unknown
example: residential
type: object
required:
- name
- address_line_1
- country_code
title: Address
AddressType:
type: string
enum:
- unknown
- residential
- commercial
- po_box
- military
title: AddressType
description: >-
The residential/commercial type of the address from the delivery/pickup
standpoint
`unknown` At the moment it is not possible to establish if the address
is of any known type
`residential` The address is a residence
`commercial` The address is associated with a business
`po_box` The address is a PO Box
`military` The address is a military address
securitySchemes:
Shippo_Token:
type: apiKey
description: |
Enter your shippo token with the ShippoToken prefix.
Example: `ShippoToken shippo_live_xxxx`
in: header
name: Authorization
x-default: 'ShippoToken '
````