openapi: 3.0.0 info: title: Polish zip codes version: '1.1' description: Polish zip codes information. contact: email: info@intami.pl externalDocs: description: API home page url: "http://kodpocztowy.intami.pl" servers: - url: 'http://kodpocztowy.intami.pl' - url: 'http://localhost:8080' paths: '/{zipCode}': parameters: - name: zipCode in: path description: A requested zip code required: true schema: type: string pattern: "^\\d{2}-\\d{3}$" example: 01-123 - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/X-TraceId" get: operationId: zip-code-info summary: Find zip code info description: Return zip code information, that is a list of zip code entries responses: '200': description: List of zip code entries or empty list when zip code was not found content: application/json: schema: type: array items: $ref: '#/components/schemas/ZipCodeEntry' headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '400': description: When path param zipCode is missing or incorrect headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '404': description: When zip code does not exists headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '429': description: In case of overlimit api call headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '/city/{city}': parameters: - name: city in: path required: true schema: type: string example: Wrocław - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/X-TraceId" get: operationId: find-zip-codes-by-city summary: Find all zip codes by city description: Return all zip codes that belong to this city. If there is more then one city with that name, all zip codes are returned. responses: '200': description: List of zip codes content: application/json: schema: $ref: '#/components/schemas/ListOfZipCodes' headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '400': description: When path param city is missing or incorrect headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '404': description: When there is no results headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '429': description: In case of overlimit api call headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '/city/{city}/street/{street}': parameters: - name: city in: path required: true schema: type: string example: Wrocław - name: street in: path required: true schema: type: string example: "Komuny paryskiej" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/X-TraceId" get: operationId: find-zip-codes-by-city-and-street summary: Find all zip codes by city and street description: Return all zip codes by street name in the city. responses: '200': description: List of zip codes content: application/json: schema: $ref: '#/components/schemas/ListOfZipCodes' headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '400': description: When path param city or street is missing or incorrect headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '404': description: When there is no results headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '429': description: In case of overlimit api call headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '/city/{city}/district/{district}': parameters: - name: city in: path required: true schema: type: string example: Wrocław - name: district in: path required: true schema: type: string example: "Oporów" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/X-TraceId" get: operationId: find-zip-codes-by-city-and-district summary: Find all zip codes by city and district description: Return all zip codes located in city's district responses: '200': description: List of zip codes content: application/json: schema: $ref: '#/components/schemas/ListOfZipCodes' headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '400': description: When path param city or district is missing or incorrect headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '404': description: When there is no results headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" '429': description: In case of overlimit api call headers: "X-TraceId": $ref: "#/components/headers/X-TraceId" components: schemas: ZipCodeEntry: title: Zip Code Information type: object description: Zip code detailed information x-examples: example: kod: 01-123 miejscowosc: Warszawa ulica: Elekcyjna gmina: Warszawa powiat: Warszawa wojewodztwo: mazowieckie dzielnica: Wola numeracja: - od: '23' do: '33' parzystosc: NIEPARZYSTE properties: kod: type: string description: zip code nazwa: type: string description: name of an institution if zip code is assigned to a specific institution miejscowosc: type: string description: town ulica: type: string description: street numer: type: string description: street number if only one number is assigned to this zip code gmina: type: string description: borough powiat: type: string description: township / district wojewodztwo: type: string description: voivodeship dzielnica: type: string description: district numeracja: type: array description: numeration schema items: $ref: '#/components/schemas/ZipCodeEntryNum' required: - kod ZipCodeEntryNum: title: Zip Code Numeration Entry type: object x-examples: num-example: od: '23' do: '33' parzystosc: NIEPARZYSTE properties: od: type: string description: numeration from do: type: string description: numeration to parzystosc: type: string description: even partity, where "PARZYSTE" = even and "NIEPARZYSTE" = odd enum: - PARZYSTE - NIEPARZYSTE required: - od - do ListOfZipCodes: title: Array Of Zip Codes type: array items: description: zip code item type: string example: "80-213" x-examples: short-list-example: [ "01-192", "01-210" ] parameters: X-TraceId: name: X-TraceId required: false in: header description: A traceId that is copied to API response header schema: type: string example: "optional_abc123" Accept: name: Accept required: true in: header description: Requested content type schema: type: string enum: - "application/json" - "application/xml" - "plain/text" example: "application/json" headers: X-TraceId: required: false schema: type: string example: "abc123" description: if request contains X-TraceId header the value will be copied here